Common issues

The most common things that go wrong, and how to fix them.

A list of the problems that come up most often, with the fix for each. If your problem is not here, the FAQ is a broader sweep, and the GitHub discussions are a good place to ask.

Tunnel won't connect

Symptom: fixedhook up hangs on "Connecting to relay…" or exits with connection refused.

Fixes, in order:

Check your network. Can you reach https://fixedhook.com from the machine? Try curl -I https://fixedhook.com.
Check your auth. Run fixedhook whoami. If it errors, run fixedhook login again.
Check the alias. Is the alias still yours? Run fixedhook aliases list and confirm the subdomain is there and not marked as deleted.
Check the CLI version. fixedhook version. Old CLIs lose compatibility with the relay after a few months; fixedhook upgrade to refresh.

If none of those work, capture the debug output with FIXEDHOOK_DEBUG=1 fixedhook up --port 3000 --alias my-app-dev and open a support ticket with the log.

Alias shows offline but the CLI is running

Symptom: the dashboard says the alias is offline, but you can see ✓ Connected to relay in the CLI output.

Causes:

The CLI is connected, but the alias name is wrong. Check that --alias my-app-dev matches a subdomain you actually own.
Another CLI is connected to the same alias. Only one tunnel can be active at a time. The most recent connection wins, and the older one is silently disconnected.
The CLI started more than 40 seconds ago and the dashboard hasn't refreshed. Refresh the dashboard. The online state is updated on each ping cycle.
Network is unstable. The CLI retries automatically; if it cannot recover, the alias goes offline. The dashboard reflects this within 40 seconds.

Provider shows 401/403 on the alias

Symptom: Stripe, GitHub, or another provider is returning auth errors to the alias URL.

Cause: in almost every case, the provider is happy with the URL itself — it is your code that is rejecting the request. The provider hits the alias, the alias forwards to your local server, and your local server returns 401 because of a bad signature verification.

Fix: open the event in the inspector and look at the response body. The 401 will be from your code, with your error message. Fix it on your side; the alias is doing its job.

Events are queued but never delivered

Symptom: events show queued status in the dashboard but never go to success or failed.

Cause: the tunnel is offline, and the events were queued. Queued events are not auto-replayed; they wait for a manual replay or for the next tunnel connection.

Fix: bring the tunnel back online (fixedhook up …) and then click Replay all queued in the alias detail view. This drains the queue one event at a time.

Signature verification fails for legitimate events

Symptom: your code says the signature is invalid, but the event is from a real provider.

Causes:

Body has been re-serialized. Your framework parsed the JSON and re-serialized it, changing whitespace. Signature schemes sign the raw bytes, not the parsed object. Use the raw request body.
Wrong signing secret. The provider's signing secret in your env does not match the one in the provider dashboard.
Clock skew. Some providers (most notably Stripe) include a timestamp in the signature. A clock skew of more than a few minutes will fail. Sync your server's clock.
Replay protection is too strict. Some signatures are valid for a window (e.g. 5 minutes). Replaying an event after that window is a legitimate failure, not a bug.

Replay button is disabled

Symptom: the Replay button is greyed out.

Causes:

The body was pruned. Events with bodies over the storage threshold are not replayable. The dashboard shows a tooltip explaining this.
The alias is deleted. Replay is only possible against an active alias.
The event is still in flight. The button is briefly disabled while the event is being recorded. Wait a second and try again.

Trial session expired

Symptom: you try to use a trial alias and get a 401.

Cause: trial sessions last 12 hours. After that, the alias is unreachable and the session token is invalid.

Fix: create a new trial session, or sign up for a free account and claim the alias. The alias subdomain is not preserved across trials; you get a new random one each time.

Rate limit hit

Symptom: API calls return 429 Too Many Requests with a Retry-After header.

Fix: the dashboard shows the retry cooldown. For CLI use, batch your calls. The current limit is 60 requests per minute per token, which is generous for normal use; if you are hitting it, you might be polling the events stream too aggressively. Use the SSE stream instead of polling.

Local dev environment issues

Symptom: the Docker stack won't start, or the web app is unreachable.

Fixes:

pnpm docker:dev from the repo root to bring up the full stack.
pnpm docker:down && pnpm docker:dev to restart cleanly.
pnpm docker:reset to nuke all volumes and start fresh. This deletes local Postgres, Redis, and MinIO data.
See the Development & E2E Testing Guide in the repo for the full local-dev reference.

Common issues

The most common things that go wrong, and how to fix them.

A list of the problems that come up most often, with the fix for each. If your problem is not here, the FAQ is a broader sweep, and the GitHub discussions are a good place to ask.

Tunnel won't connect

Symptom: fixedhook up hangs on "Connecting to relay…" or exits with connection refused.

Fixes, in order:

Check your network. Can you reach https://fixedhook.com from the machine? Try curl -I https://fixedhook.com.
Check your auth. Run fixedhook whoami. If it errors, run fixedhook login again.
Check the alias. Is the alias still yours? Run fixedhook aliases list and confirm the subdomain is there and not marked as deleted.
Check the CLI version. fixedhook version. Old CLIs lose compatibility with the relay after a few months; fixedhook upgrade to refresh.

If none of those work, capture the debug output with FIXEDHOOK_DEBUG=1 fixedhook up --port 3000 --alias my-app-dev and open a support ticket with the log.

Alias shows offline but the CLI is running

Symptom: the dashboard says the alias is offline, but you can see ✓ Connected to relay in the CLI output.

Causes:

The CLI is connected, but the alias name is wrong. Check that --alias my-app-dev matches a subdomain you actually own.
Another CLI is connected to the same alias. Only one tunnel can be active at a time. The most recent connection wins, and the older one is silently disconnected.
The CLI started more than 40 seconds ago and the dashboard hasn't refreshed. Refresh the dashboard. The online state is updated on each ping cycle.
Network is unstable. The CLI retries automatically; if it cannot recover, the alias goes offline. The dashboard reflects this within 40 seconds.

Provider shows 401/403 on the alias

Symptom: Stripe, GitHub, or another provider is returning auth errors to the alias URL.

Fix: open the event in the inspector and look at the response body. The 401 will be from your code, with your error message. Fix it on your side; the alias is doing its job.

Events are queued but never delivered

Symptom: events show queued status in the dashboard but never go to success or failed.

Cause: the tunnel is offline, and the events were queued. Queued events are not auto-replayed; they wait for a manual replay or for the next tunnel connection.

Fix: bring the tunnel back online (fixedhook up …) and then click Replay all queued in the alias detail view. This drains the queue one event at a time.

Signature verification fails for legitimate events

Symptom: your code says the signature is invalid, but the event is from a real provider.

Causes:

Body has been re-serialized. Your framework parsed the JSON and re-serialized it, changing whitespace. Signature schemes sign the raw bytes, not the parsed object. Use the raw request body.
Wrong signing secret. The provider's signing secret in your env does not match the one in the provider dashboard.
Clock skew. Some providers (most notably Stripe) include a timestamp in the signature. A clock skew of more than a few minutes will fail. Sync your server's clock.
Replay protection is too strict. Some signatures are valid for a window (e.g. 5 minutes). Replaying an event after that window is a legitimate failure, not a bug.

Replay button is disabled

Symptom: the Replay button is greyed out.

Causes:

The body was pruned. Events with bodies over the storage threshold are not replayable. The dashboard shows a tooltip explaining this.
The alias is deleted. Replay is only possible against an active alias.
The event is still in flight. The button is briefly disabled while the event is being recorded. Wait a second and try again.

Trial session expired

Symptom: you try to use a trial alias and get a 401.

Cause: trial sessions last 12 hours. After that, the alias is unreachable and the session token is invalid.

Fix: create a new trial session, or sign up for a free account and claim the alias. The alias subdomain is not preserved across trials; you get a new random one each time.

Rate limit hit

Symptom: API calls return 429 Too Many Requests with a Retry-After header.

Local dev environment issues

Symptom: the Docker stack won't start, or the web app is unreachable.

Fixes:

pnpm docker:dev from the repo root to bring up the full stack.
pnpm docker:down && pnpm docker:dev to restart cleanly.
pnpm docker:reset to nuke all volumes and start fresh. This deletes local Postgres, Redis, and MinIO data.
See the Development & E2E Testing Guide in the repo for the full local-dev reference.