Troubleshooting

Start by reading the logs. Almost every problem here announces itself there:

docker compose logs tor

My address isn't up yet

Most common cause: it's just not finished booting. The first start takes a few minutes. Tor has to connect, bootstrap to 100%, build a circuit, and publish your service, and with proof-of-work and six introduction points that can take longer than you'd expect. Give it two to three minutes.

Check whether it's still working or actually stuck:

docker compose ps            # is the container "healthy" yet?
docker compose logs tor      # look for "Bootstrapped 100%"

The container only reports "healthy" once Tor is fully bootstrapped and has a circuit, so wait for that rather than the first sign of life. If it's still not healthy after several minutes, read on.

The .onion loads but shows an error, not my site

Tor is working; the problem is between Tor and your backend.

• Is the backend on the internal network? It must share tor-internal with the tor container. If it's on a different network, Tor can't reach it.
• Do the name and port match? In 80:web:80, the middle part must be the exact service name of your backend in the compose file, and the last part must be the port it actually listens on.
• Did you rebuild the backend? HiddenForge looks up the backend's address once at startup. If you recreated the backend and it got a new internal IP, recreate the tor container too so it re-runs the lookup: docker compose up -d.

One of my services is missing

If you run several services and one didn't appear, it was almost certainly skipped, not fatal. HiddenForge skips a bad entry and keeps going. Search the logs:

docker compose logs tor | grep -i skip

• Skipping invalid service name means the variable prefix produced a name Tor won't accept (it must be lowercase letters, digits, and hyphens, start with a letter or digit, and be at most 63 characters).
• Skipping invalid mapping or Skipping malformed mapping means a port was out of range or a mapping wasn't in port:name:port form.
• A "cannot resolve" message means the backend name doesn't exist on the network. Is that backend running and on tor-internal?

Fix the offending variable and recreate the container.

The container won't stay running

A bad service name or a bad port does not stop the container; those are skipped with a warning. If the container actually exits, the cause is lower-level, usually a filesystem or permission problem writing the config or fixing key-folder ownership. Read the last lines of the log for the real error. A common culprit is a key folder with ownership the container can't adjust, so make sure the mounted tor-keys folder is writable by the container.

The logs say Vanguards didn't start

You'll see a line like "control socket not found ... Continuing without Vanguards." Your service still works; it falls back to Tor's built-in vanguards-lite protection. It's worth investigating (usually Tor was slow to come up), but it's not an outage.

Tor can't reach the network at all

The tor container needs outbound internet to reach the Tor network. Make sure it's on the tor-external network (the non-internal one). Your backend must not be on that network; only Tor.

Other network causes:

• A firewall on the host blocking outbound connections Tor needs.
• seccomp=unconfined was stripped. Some managed container platforms remove custom security options. Without it, Tor's own sandbox can conflict with the host's default filter. If you're on such a platform and Tor won't start, this is a likely cause.

Nothing works and the clock looks wrong

Tor needs the host clock to be roughly correct, within about 30 minutes of real time. If the host clock has drifted, Tor can't validate the network consensus and won't bootstrap. Fix the host's time sync and restart.

Still stuck

Collect the full docker compose logs tor, note your Docker or Podman version, and bring it to the project's channels. The logs almost always contain the specific line that explains it.