What Should You Check When a Self-Hosted App Opens Locally but Its API Cannot Be Reached?

A locally opening page does not prove its API path works; the browser interface and backend request may use different hosts, ports, protocols, or credentials.

On a home server, the HTML and static assets may load from a reverse proxy, browser cache, or local web container while API calls travel to another service, subpath, WebSocket endpoint, or externally configured base URL. Start by capturing one failed request in the browser, replay it from the relevant network boundary, and then separate routing, TLS, authentication, browser policy, and application configuration instead of treating the visible page as proof that the whole stack is reachable.

Prove Whether the Page and API Use the Same Network Path

Open the browser’s developer tools and reload the failing action. Record the request URL, method, status, response body, remote address, initiator, and whether the failure is an ordinary HTTP request, WebSocket, server-sent event, or background fetch.

A self-hosted Baserow case showed a usable interface repeatedly reporting reconnection because the browser’s event channel followed a different proxy path. The visible symptom was a failed event connection, not a complete web-server outage.

Compare the successful document request with the failed API request character by character: scheme, hostname, port, path prefix, and query string. If they differ, investigate the first changed layer. If they are identical, continue with headers, cookies, response handling, and backend routing.

Replay the Exact Request From Each Relevant Boundary

Copy one failed request as a command and replay it from the client, the reverse-proxy host, and a temporary container attached to the application network. Preserve its method, authorization header, content type, body, and expected hostname.

An API can be reachable at the TCP and HTTP layers yet reject the real request because a token or header is absent. A FreshRSS API discussion narrowed an external failure to missing authorization context rather than general container reachability.

Interpret the earliest failing boundary. DNS failure points to name resolution; connection refusal points to the listener, port, or network; a TLS error points to identity or trust; 401 or 403 points to authentication or policy; 404 often points to routing or subpath rewriting; and a successful direct call with a failed browser call moves the diagnosis toward proxy or browser rules.

Check the API Base URL, Port, and Subpath

Inspect the application’s public URL, API URL, WebSocket URL, base path, and frontend build-time variables. A locally served interface may contain an absolute API address that points to an old domain, private IP, wrong port, or root path that exists only on the server.

Subpath deployments are especially sensitive to slash handling and rewrite rules. A Frigate reverse-proxy case traced failed resources to subpath rewrite behavior even though the main interface could be reached.

Test the API endpoint both with and without the configured prefix only to identify the correct route, then fix the application and proxy to agree on one canonical path. Do not keep duplicate rewrite exceptions that make some methods work while uploads, callbacks, or streaming endpoints continue to bypass the intended backend.

Featured

ZimaCube 2 Personal Cloud Home NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

Verify Reverse-Proxy Headers, TLS, and Streaming Support

Compare the proxy route for ordinary pages with the route for API, WebSocket, and streaming requests. Confirm the upstream service name, internal port, HTTP version, connection upgrade behavior, read timeout, buffering policy, and forwarded host and protocol headers.

Open WebUI users have reported an interface that appears functional while proxied API output stalls because buffering or streaming behavior differs from direct access. The diagnostic focus is the proxied streaming path, not the static page.

Send the original hostname and scheme to the backend through narrowly configured trusted-proxy headers. Enable WebSocket upgrades only on routes that need them, disable inappropriate buffering for streaming endpoints, and verify that the proxy uses the application’s internal listener rather than the published host port by accident.

Separate Browser Policy From Server Reachability

When a direct command succeeds but the browser fails, inspect the browser console for CORS, mixed-content, certificate, cookie, and preflight errors. The server may answer correctly while the browser refuses to expose or send the request.

A reverse-proxied Open WebUI discussion links WebSocket and API failures with origin and forwarded-protocol handling, showing why origin and protocol identity must remain consistent through the proxy.

Confirm that an HTTPS page never calls an HTTP API, that the API permits only the required origin, that preflight requests reach the same route, and that session cookies use the correct domain, path, Secure, and SameSite attributes. Avoid disabling browser protections globally; repair the server’s public identity and policy instead.

Validate the Full API Workflow From Every Required Network

After the first failed request works, test login, list or search, create or update, upload, download, background events, and one token refresh from the LAN and every supported remote path. A single successful GET does not prove that authenticated writes or long-lived connections are repaired.

The ZimaSpace workflow for separating IP reachability from domain routing is the next step when direct API calls work by address but fail through the public hostname.

The issue is resolved only when the browser and non-browser client use the intended canonical endpoint, the proxy reaches the correct backend, authentication survives redirects, browser policy accepts the response, and streaming or WebSocket sessions remain stable. Preserve the captured failing request as a regression test for future upgrades.