Troubleshooting

Keep useful, safe evidence

Record time, page, operation, HTTP status and a redacted error. Distinguish no data, no permission, pending processing and service failure. Never paste codes, cookies, access tokens, grants, complete share links or user records into Ask Docs.

Sign-in and mail

| Symptom | Check and next step | | --- | --- | | Mail missing | Address and spam folder; wait 60 seconds; 202 is not actual receipt | | Six digits rejected | Latest challenge, same email, leading zeros, 10-minute lifetime and unconsumed state | | 429 | Wait for limits or obtain a new valid challenge; do not keep guessing | | Local port 8025 has no inbox | fake-email has no public inbox UI; private test reads require a token absent from the default overlay | | Signed out after reload | Correct HTTPS same-origin entry point, cookie and session validity; sign in again | | Old password/invitation flow fails | The active flow uses email codes; archived registration instructions do not apply |

Uploads and files

| Symptom | Check and next step | | --- | --- | | Processing after 100% | Parts arrived; wait and refresh, then inspect version, size and downloaded content | | Same-name new upload conflicts | No automatic overwrite; use the target fileId's replacement-intent API when replacing | | Empty file rejected | Choose a nonempty file; sizeBytes must be a positive decimal string | | Upload 401 | uploadGrant lasts at most 300 seconds, not the intent's 15 minutes | | Cancellation failed or space stays reserved | Reread quota and intent/expiry state; avoid multiplying reservations | | File exists but cannot download | currentVersion may still be null; a name alone does not prove finalization | | No delete, move or restore button | These complete operations are absent from the current account page |

For stuck processing, operators inspect storage-worker, Core callbacks, Redis, object storage and database. Do not invoke internal completion from the browser or directly alter quota records.

Downloads, shares and publications

Tickets last 60 seconds and are single-use. A stale address or reused grant fails; initiate a new download for a new ticket. Blob-based browser downloads can require considerable memory and are affected by network interruptions.

A share 404 may mean password failure, expiry, exhausted allowance, revocation or unavailable files. Ask the sender. Ticket issuance consumes the share allowance; interrupted transfer does not guarantee a refund. Successful Download metrics use a different completion criterion.

An upload is not automatically listed on /download; it needs published status. Draft and disabled records stay private. The current catalogue only reads the first page and has no pagination controls; inspect the paginated API if necessary. The admin publication page lists the administrator's own files.

Administrative data

Resolve identity/role for 401/403 and dependencies for 503. Empty results differ from loading errors. partial/unavailable or null system-health values are not healthy zeros. Check freshness, coverage and the Asia/Shanghai date range for analytics.

Requery notifications after SSE reconnects rather than expecting history replay. Read state does not establish incident resolution.

Local runtime and releases

If Docker cannot connect, start your Docker service. Old Compose cannot apply !override correctly. Inspect ./manage-services.sh status, logs core-api and logs storage-worker. reset --confirm deletes local data volumes and is not a substitute for diagnosis.

Production exit 75 indicates an active release lock; inspect the current release instead of removing its lock. Rollback requires a recorded manifest and does not restore backups automatically. See Local development and Deployment.