Storage

Image upload flow

Images are uploaded in a secure flow that uses signed URLs.

Upload steps

1. The client hashes the image with SHA256.
2. The server issues a signed upload URL.
3. The image is uploaded to the avatar bucket.
4. The server stores the hash file name in the database.

Image hashing rules

Hashing ensures consistent storage and naming.

Hash requirements

• SHA256 hash of the file contents.
• File name is hash.png.
• Bucket is avatar.

Folder rules

• Profile images use folder {profileId}.
• Workspace images use folder {workspaceId}.

Avatar URL behavior

Image URLs are built on the server and sent to the client.

How URLs are built

• The database stores only hash.png.
• The server builds /storage/avatar/{folderId}/hash.png.

Fallbacks

• If an image fails to load, initials are shown.
• If no image is set, initials are used by default.

Troubleshooting

Use these fixes when image uploads fail.

Failed to generate upload URL

• Retry the upload.
• Check that the file hash is valid.

Storage resource not found

• Confirm the bucket name is avatar.
• Ensure the folder ID matches the profile or workspace ID.

Upload rejected

• Use PNG, JPG, or SVG.
• Keep the file under 2 MB.

Image not visible

• Refresh the page.
• Check that the image URL is reachable.