Troubleshooting

Start with the logs and the health check. Most problems show up in one of them.

Read the logs

Homestead logs to standard output. In a container it writes JSON lines; in a terminal, plain text.

docker logs homestead

With Compose:

docker compose -f deploy/compose.yaml logs homestead

For more detail, set HOMESTEAD_LOG_LEVEL=debug (the levels are debug, info, warn and error). With docker run, remove the container and start it again with the variable; your data stays in the volume:

docker rm -f homestead

docker run -d --name homestead -p 8080:8080 -v homestead-data:/data -e HOMESTEAD_LOG_LEVEL=debug homestead

With Compose, add it under environment: in deploy/compose.yaml and run up -d again.

Check health

curl http://localhost:8080/api/v1/health

Reply	Meaning
`"status":"ok"`	The API is serving and the database answers.
`"status":"degraded"` with `"dbOk":false`	The server runs but can’t reach its database. Check the data volume and the logs.
No reply	The server isn’t running or the port isn’t published. Check `docker ps` and the logs.

The server won’t start

The logs name the setting at fault. Homestead refuses to start when:

HOMESTEAD_LOG_LEVEL isn’t debug, info, warn or error,
HOMESTEAD_MDNS isn’t a boolean (true, 1, yes, false, 0 or no),
an entry in HOMESTEAD_TRUSTED_PROXIES isn’t a valid CIDR,
HOMESTEAD_LISTEN is empty.

If port 8080 is taken on the host, publish another one, such as -p 8081:8080.

The browser shows “not implemented” at port 8080

On main the server doesn’t serve the web app yet, so http://localhost:8080/ answers 501 not_implemented. The API is fine. Run the web app’s development server and use http://localhost:5173, as in Quick start.

Saving fails with “cross-origin request rejected”

You can sign in, but adding or editing gives a 403 with cross-origin request rejected, or sign-in doesn’t stick at all. This almost always means HOMESTEAD_BASE_URL doesn’t match the address in your browser.

The compose file sets it to the example https://home.example.com. Delete that line, or set your real address. See Docker Compose.
With an https:// base URL, cookies are marked secure and saving only works from that exact origin, so opening Homestead at http://192.168.…:8080 won’t work. Use the public address, or remove the base URL for home-only use.

Sign-in is limited to 10 attempts a minute per IP address, and 5 failed attempts lock that username for 15 minutes. Wait and try again. A 429 reply carries Retry-After in seconds.

Reset a password

Anyone with shell access to the server can reset a member’s password. It also signs out all of that member’s sessions.

docker exec homestead homestead user reset-password mali

Homestead makes a random password and prints it once. To choose the password yourself, pass --password-file with a file, or - to read it from standard input.

Setup has already been done for this data volume. Sign in instead. If you want to start over, deleting the volume deletes the whole household; make a backup first.

Account statuses

Each account on a person page shows its status.

Status	What to do
`pending` (“Waiting for first fetch”)	Wait for the first fetch. Server-tier accounts fetch within their interval; agent-tier ones wait for an agent.
`needs_agent` (“Needs an agent”)	The platform blocked the server. Connect an agent that can fetch it; see Connect an agent.
`login_required` (“Agent needs to log in”)	Log in to that platform in your agent’s browser. Homestead tries again 6 hours later.
`error` (“Couldn’t fetch”)	Several failures in a row, or the site blocked your agent. Homestead backs off and tries again; check the agent’s logs.
`not_found` (“Account not found”)	The handle is wrong or the profile is gone. Edit the account.
`closed` (“Visit only”)	A closed platform. This is expected; you’ll get visit suggestions.

“Monthly X budget reached. Fetching resumes next month.” means the X budget guard skipped calls; see Use your X API key.

Everyone on Instagram shows up as a visit suggestion

Agent-tier accounts with no active agent token become “source unavailable” hearth picks, and the feed shows one banner: “Connect an agent to see Instagram stories”. Connect an agent, or add these people’s other accounts.

The phone app can’t find the server on Wi-Fi

The server announces _homestead._tcp on the LAN, and logs advertising on the LAN when it does, or mdns: not advertising on the LAN when it can’t. In Docker’s default bridge network the announcement can’t reach the LAN, so nothing appears. On Linux, use host networking; see Open on your phone. Or choose Enter address in the app.

The pairing QR code doesn’t work on my phone

The QR code carries the server address Homestead knows. If you made it while browsing at localhost, the phone gets localhost. Open Homestead on your computer at its network address, or set HOMESTEAD_BASE_URL, then make a new code. Codes expire after 10 minutes.

Restore refuses to run

“already holds a Homestead instance … stop the server and pass —force” means the data volume isn’t empty. Stop the server first, then add --force. See Backup and restore.

The companion gets 501 errors

The server’s captures API isn’t built on main yet, so it answers 501 not_implemented.

Available on main

API errors

Every API error is application/problem+json with a stable code. The list is in Errors.