Model Downloads Behind a Captive Portal

Direct answer

A captive portal is a network-access state, not evidence that the model file is corrupt. Before treating a large transfer as failed, check Android’s network capabilities: a network can advertise internet access while also reporting a captive portal and lacking validated public connectivity. Explain that the user may need to sign in to the network, pause the model request, and resume only after connectivity is validated and the artifact identity still matches. Never try to bypass the portal, suppress its login flow, disable TLS checks, or append a login page to a model file. This situation differs from a hostile redirect returned by a model host. A captive portal is a legitimate network requiring user action; a download redirect or HTML response from an artifact endpoint is a content-validation event. Both must be handled safely, but the remedy is different. For a portal, the application should leave the signed-in interaction to Android or the user’s browser and wait for network state changes. For a suspicious model response, reject the body and preserve the existing artifact. Do not tell the user to accept a certificate warning or paste credentials into the model app. Android’s NetworkCapabilities exposes NET_CAPABILITY_CAPTIVE_PORTAL for a network found to require portal interaction and NET_CAPABILITY_VALIDATED after the system validates public internet access. Capabilities can change. Treat them as useful signals, not a guarantee that the specific model host is reachable or that a later request will succeed. A validated connection can still lose signal, be filtered, require authentication for a particular service, or return an unexpected response. The downloader remains responsible for status code, content type, byte range, artifact revision, and integrity rules. Keep transfer state safe while the user signs in. Do not repeatedly retry a large file against an unauthenticated portal endpoint. If no bytes have been accepted, keep the transfer queued or paused and show a clear wait/sign-in message. If a partial artifact exists, preserve it only with its artifact identity, accepted offset, and metadata; after connectivity returns, request a valid range and verify that the response continues the same representation. An HTTP 200 login page is not a successful model response. If the response is HTML, the range is wrong, or the representation changed, reject it and follow a tested restart or repair path. Do not collect portal credentials. The operating system or Wi-Fi provider handles sign-in; the model download code should not scrape a browser page, store a portal password, or send model prompts and user data to a captive-portal endpoint. Logs should record a safe category such as “network not validated” and a timestamp, not the user’s credentials, full portal URL with query parameters, or model request headers. The app should not claim a privacy breach merely because a portal blocked transfer; describe what is known and which network step remains. Retry behavior needs a state transition, not a timer loop. Observe connectivity changes and offer a user-controlled retry when the network becomes validated. Use backoff for ordinary transient failures, but do not repeatedly fetch a login response while capability remains captive. If the user changes networks, re-check the transfer source and resume metadata. If the file identity cannot be confirmed after the interruption, restart a new candidate rather than mixing bytes. The old active model and all user-created data remain separate from temporary download data.

A model transfer meets airport Wi-Fi sign-in

The phone is on airport Wi-Fi with internet capability but no validated access. A request to the model endpoint returns a small HTML sign-in page while a transfer may have partial bytes.

Decision

Stop writes, preserve only a known-identity candidate, let the user complete portal sign-in through the platform, and retry after connectivity validation.

Expected outcome

Portal content never becomes model bytes, and a later request resumes only when its range and artifact identity are proven.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Response content and status checks
• Temporary-file isolation
• Recovery after login

A completed byte stream is not enough. Final placement, integrity, runtime load, and recovery must also pass.

Implementation workflow

1. Inspect current network capabilities. Distinguish configured internet, captive portal detection, and validated public connectivity from the actual active network. A Wi-Fi icon alone does not prove the model service is reachable.
2. Pause while portal sign-in is required. Explain that network authentication may be needed and leave that interaction to Android or the user’s browser. Do not repeatedly request the model or collect the portal password in the app.
3. Protect partial model bytes. Retain a temporary file only if its revision, source, accepted byte offset, and response metadata are known. Never write an HTML portal page or login redirect body into the candidate.
4. Resume after network changes. Wait for validated connectivity or explicit retry, then request the accepted range and verify response status, exact offset, artifact identity, and expected content type.
5. Reject unexpected response data. A login document, wrong range, changed revision, or unknown type must stop the transfer and use the documented repair or restart path instead of appending bytes.
6. Exercise transitions safely. Test portal detection, user login, validation, portal return, network switch, cancellation, partial transfer, and later resume. Confirm logs never retain credentials or signed URLs.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• Portal state is distinguishable from artifact-integrity failure and an ordinary transient timeout.
• Portal response bytes are never appended to a model file, and neither TLS nor platform sign-in protections are bypassed.
• Retry follows user action or observed recovery and revalidates the same artifact revision and byte offset.
• Portal credentials, signed URLs, and model input are not collected or placed in diagnostics.

Decision table

Failure patterns to prevent

• Trusting a 200 response
• Appending portal content to a partial model

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Read network state on Android
• Android NetworkCapabilities API
• RFC 9110: HTTP range requests and validators

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions