Practical guide · AI & interfaces
7 min read
Updated
File upload: progress, validation, and recovery
Specify file selection, trustworthy progress, server checks, storage permissions, cancellation, and retry.
Direct answer
An upload workflow connects a labeled native file picker to a transfer service, server validation, and controlled storage. Show measured transfer progress separately from server processing, and define cancellation and retry outcomes. The atlas documents this workflow; its UI components do not provide an upload service.
01
1. Define the service boundary
An upload workflow needs a native file picker, a transfer service, server validation, and controlled storage. A button and progress bar only present actions and state; this guide does not add an upload service to the atlas.
Prerequisites: a test backend, agreed accepted formats and size limits, storage owner, access policy, and cleanup policy. Example contract: one PDF attachment, at most 5 MB, private to its owner, unavailable until checks finish. Decide what “ready” means before drawing the success state.
02
2. Make selection usable
Provide a labeled input type="file", visible format and size instructions, and a separate upload action. Keep native keyboard access; drag-and-drop may supplement it. Show the selected filename as text, size, and an explicit remove or replace action. Dismissing the picker must leave the current selection coherent.
The accept attribute helps choose files but does not enforce their validity. Check count and size locally for quick feedback, and keep rejected files out of the send queue with a specific correction. Selection is not transfer; do not say “uploaded” at this stage.
03
3. Separate transfer from processing
Define selected, transferring, checking, ready, rejected, interrupted, and canceled states. Derive a percentage only from a measurable byte total, for example upload progress events with lengthComputable. If the total is unknown, show indeterminate progress with a useful text label rather than inventing a percentage.
After all bytes leave the browser, show “Checking file” until the service confirms acceptance and storage. Label the progress indicator and announce meaningful stage changes without announcing every byte update. Associate any failure with the file and leave a next action visible.
- Transferring: show measured bytes or an indeterminate indicator.
- Checking: wait for server acceptance without implying the file is already available.
- Ready: expose the next action only when the stored object is accepted.
04
4. Enforce acceptance on the server
Authenticate and authorize the operation. Enforce count and size limits, allowlisted extensions and inspected file content; do not trust a client MIME type or filename. Generate storage names, isolate files from executable web content, and apply malware scanning or content disarm where appropriate. Protect cookie-authenticated upload endpoints against CSRF.
Keep unverified objects quarantined and enforce access checks on retrieval as well as upload. Avoid public-by-default storage and unnecessary filename logging. Define expiry and deletion for abandoned uploads. These controls need backend implementation and verification; a UI validation message cannot establish that a file is safe.
05
5. Cancel, retry, and verify
Cancellation stops the active client request where supported; it does not prove deletion of bytes already stored. Have the backend cancel or expire the upload session and report the final status. On interruption, keep metadata and offer retry; do not claim resumable transfer unless the protocol implements it. A reload can require selecting the file again.
Use an operation identifier to reconcile uncertain outcomes and avoid duplicate objects on retry. Test a small valid file, an oversized file, a misleading extension, connection loss, cancellation, and expired authorization against the test backend. Verify progress stages, keyboard recovery, exactly one accepted object, and refusal of access from another account. Use harmless fixtures; record backend evidence separately from UI mocks.
Keep this
Evidence to keep
- 01Ready follows server validation and storage confirmation.
- 02Cancel and retry have verified backend outcomes.
- 03Private retrieval and rejection rules are tested independently of UI.
- 04File selection, replacement, and removal are reachable using only the keyboard.
- 05Unknown byte totals show indeterminate progress instead of a fabricated percentage.
- 06Oversized and misleadingly named fixtures receive a specific rejection and a next action.
Primary sources
Technical claims in this guide connect to first-party specifications and documentation.
- File input (opens in a new tab)MDN · Primary reference supporting the procedure; examples and workflow are original editorial guidance.
- Upload events (opens in a new tab)MDN · Primary reference supporting the procedure; examples and workflow are original editorial guidance.
- File Upload Cheat Sheet (opens in a new tab)OWASP · Primary reference supporting the procedure; examples and workflow are original editorial guidance.
Continue
Related guides and tools
Understand → Recognize → Choose → Compare
Pack for your agent
Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.
Implement correctly
Apply “File upload: progress, validation, and recovery” step by step
# Apply the “File upload: progress, validation, and recovery” guide in your agent ## Objective An upload workflow connects a labeled native file picker to a transfer service, server validation, and controlled storage. Show measured transfer progress separately from server processing, and define cancellation and retry outcomes. The atlas documents this workflow; its UI components do not provide an upload service. ## Prerequisites - Inspect the repository, documentation, and existing conventions. - Confirm the need matches the guide scope: Specify file selection, trustworthy progress, server checks, storage permissions, cancellation, and retry. - Preserve the correct decisions already in place. ## Guide steps - 1. 1. Define the service boundary — An upload workflow needs a native file picker, a transfer service, server validation, and controlled storage. A button and progress bar only present actions and state; this guide does not add an upload service to the atlas. - 2. 2. Make selection usable — Provide a labeled input type="file", visible format and size instructions, and a separate upload action. Keep native keyboard access; drag-and-drop may supplement it. Show the selected filename as text, size, and an explicit remove or replace action. Dismissing the picker must leave the current selection coherent. - 3. 3. Separate transfer from processing — Define selected, transferring, checking, ready, rejected, interrupted, and canceled states. Derive a percentage only from a measurable byte total, for example upload progress events with lengthComputable. If the total is unknown, show indeterminate progress with a useful text label rather than inventing a percentage. - 4. 4. Enforce acceptance on the server — Authenticate and authorize the operation. Enforce count and size limits, allowlisted extensions and inspected file content; do not trust a client MIME type or filename. Generate storage names, isolate files from executable web content, and apply malware scanning or content disarm where appropriate. Protect cookie-authenticated upload endpoints against CSRF. - 5. 5. Cancel, retry, and verify — Cancellation stops the active client request where supported; it does not prove deletion of bytes already stored. Have the backend cancel or expire the upload session and report the final status. On interruption, keep metadata and offer retry; do not claim resumable transfer unless the protocol implements it. A reload can require selecting the file again. ## Acceptance criteria — Evidence to keep - Ready follows server validation and storage confirmation. - Cancel and retry have verified backend outcomes. - Private retrieval and rejection rules are tested independently of UI. - File selection, replacement, and removal are reachable using only the keyboard. - Unknown byte totals show indeterminate progress instead of a fabricated percentage. - Oversized and misleadingly named fixtures receive a specific rejection and a next action. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The steps come from a published, sourced guide, not improvisation.
- The checklist turns advice into verifiable criteria.
- The declared scope keeps the guide within its evidence.
Try next
Anchor the guide in the project
# Anchor the guide in the project ## Objective Turn the applied steps into durable repository conventions. ## Checks - Link each decision made to the guide step that justifies it. - Add the checklist to the relevant reviews. - Record out-of-scope cases for the neighboring guides. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:557d669b95ed8f1ff0271c7126c1976723da1bdc1083a73880fc08a64e83ae2f
Diagnose a problem
Diagnose a “File upload: progress, validation, and recovery” guide gap
# Diagnose a failed application of the “File upload: progress, validation, and recovery” guide ## Observed symptom [DESCRIBE THE SYMPTOM HERE] ## Observable checks - Replay the steps in order and note the first one that diverges: - 1. 1. Define the service boundary — An upload workflow needs a native file picker, a transfer service, server validation, and controlled storage. A button and progress bar only present actions and state; this guide does not add an upload service to the atlas. - 2. 2. Make selection usable — Provide a labeled input type="file", visible format and size instructions, and a separate upload action. Keep native keyboard access; drag-and-drop may supplement it. Show the selected filename as text, size, and an explicit remove or replace action. Dismissing the picker must leave the current selection coherent. - 3. 3. Separate transfer from processing — Define selected, transferring, checking, ready, rejected, interrupted, and canceled states. Derive a percentage only from a measurable byte total, for example upload progress events with lengthComputable. If the total is unknown, show indeterminate progress with a useful text label rather than inventing a percentage. - 4. 4. Enforce acceptance on the server — Authenticate and authorize the operation. Enforce count and size limits, allowlisted extensions and inspected file content; do not trust a client MIME type or filename. Generate storage names, isolate files from executable web content, and apply malware scanning or content disarm where appropriate. Protect cookie-authenticated upload endpoints against CSRF. - 5. 5. Cancel, retry, and verify — Cancellation stops the active client request where supported; it does not prove deletion of bytes already stored. Have the backend cancel or expire the upload session and report the final status. On interruption, keep metadata and offer retry; do not claim resumable transfer unless the protocol implements it. A reload can require selecting the file again. ## Possible causes - A step was skipped or executed out of order. - The actual need falls outside the guide scope. - A checklist criterion was never verified. ## Bounded fixes - Redo only the diverging step and what depends on it. - Document the gap if the guide scope does not cover the need. ## Final verification — Evidence to keep - Ready follows server validation and storage confirmation. - Cancel and retry have verified backend outcomes. - Private retrieval and rejection rules are tested independently of UI. - File selection, replacement, and removal are reachable using only the keyboard. - Unknown byte totals show indeterminate progress instead of a fabricated percentage. - Oversized and misleadingly named fixtures receive a specific rejection and a next action. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The diagnosis replays ordered steps instead of searching at random.
- Fixes stay bounded to the first real divergence.
- The checklist serves as a reproducible final verification.
Try next
Prevent the next drift
# Prevent the next drift ## Objective Turn the first diverging step into an explicit project check. ## Checks - Add a focused check on the step that diverged. - Verify the checklist on a second real case. - Document the scope limit you hit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:193d9566032a7a722504b0e7453411bb1683d3e866e396b8d6bd03c82e3b4f51
Pack digest: sha256:e077d4b8202087ea608a57d72153171c7a6fa9d88fa56099573e15ba412c5d97