Common Issues

Reading the error messages

The web app routes most error toasts through a single error handler that produces consistent messages. Knowing what each status code maps to lets you skip the guesswork.

Status	Toast text (after the action context)	What it usually means
0	”Unable to connect to the server.”	Your browser couldn’t reach the API. Check your internet connection or VPN. The server itself is fine — your request never arrived.
400	The server’s specific validation message — or “Please check your input.” as fallback	A field you submitted is missing or malformed. The toast usually shows the exact problem.
401	”Your session has expired. Please log in again.”	Your auth token timed out. Sign in again.
403	”{action}: You do not have permission for this action.”	Your role doesn’t permit this. The action name is included so you know which call was rejected.
404	”{action}: The requested item was not found.”	The record no longer exists. Often someone else deleted it; refresh the page.
409	”{action}: A conflict occurred. Please refresh and try again.”	Optimistic concurrency conflict — someone else saved the same record while you were editing. Refresh, redo your changes, save again.
500 / 502 / 503	”{action}: Server error. Please try again later.”	A server-side problem. Try again in a minute. If it persists, contact support.
anything else	”{action}: An unexpected error occurred.”	The handler didn’t recognise the response. Check the browser console for more detail and share with support if needed.

When the toast carries a trace id

For requests that match the structured error format, the handler also displays a trace id. If you report the issue, include the trace id — support can find the corresponding server log entry from it.

Specific surface troubleshooting

Some pages have richer error handling than the generic mapping above:

• Encounter submission — see Creating Encounters → What happens after submission for the upload retry/skip flow.
• Encounter ML pipeline — see Submissions → Stages for what each ML state means.
• Author approval flow on exports — declined approval requests can be re-approved; see the Export Approval section in Creating Encounters for the license interaction.

For desktop-client-specific issues (sync, photographer resolution, cloud discovery), the desktop docs have their own troubleshooting page: Sync Troubleshooting.

When this page doesn’t help

If your error doesn’t match any of the codes above, or the same error keeps recurring even after the suggested action, the next step is to capture context for support:

• The exact toast text
• The trace id, if shown
• The page URL when the error happened
• What you were doing right before it appeared
• The browser’s dev tools console, if you can copy any errors logged there

Related

• Upload Errors — upload-specific failure modes
• ML Issues — when ML metrics or annotations behave unexpectedly
• ML Center Overview — for understanding what the metrics dashboards show