Troubleshooting

“No machine” / auth required

Most “auth is broken” symptoms are one of:

• you opened the wrong stack URL (browser origin collision)
• the stack did not get seeded auth (non-main stacks)
• the stack is pointed at an unexpected repo checkout

Check:

hstack where
hstack stack info <stack>

Fix auth seeding:

hstack auth seed
hstack auth seed --force
hstack stack auth <stack> copy-from dev-auth

If the stack already has seeded auth but still fails with an auth error or a daemon 401, repair the stack-scoped login state directly:

hstack stack auth <stack> login --force

This is safer than deleting files by hand. In current builds, --force clears stale stack-specific aliases before reauth and keeps unrelated credentials untouched.

“This stack is using the wrong checkout”

Check the pinned repo:

hstack stack info <stack>
cat ~/.happier/stacks/<stack>/env | rg HAPPIER_STACK_REPO_DIR

Repoint:

hstack stack wt <stack> -- use dev
# or:
hstack stack wt <stack> -- use pr/123-some-pr

Port collisions

If hstack refuses to start because a pinned port is in use:

• stop the stack: hstack stack stop <stack>
• or unpin ports (then re-run start/dev):
  • use hstack stack edit <stack> --interactive, or
  • hstack stack audit --fix-ports

Stack is unhealthy / can’t reach server

hstack stack doctor <stack>
hstack logs:tail

If you’re using full server (happier-server), verify Docker:

docker ps

If the stack is supposed to use a runtime snapshot, inspect that explicitly:

hstack stack info <stack>
hstack stack info <stack> --json
hstack stack doctor <stack> --json

Look for:

• runtime.mode
• runtime.activeSnapshotId
• runtime.snapshotPath
• runtime.valid
• runtime.errors

Common fixes:

# rebuild and activate a fresh runtime snapshot
hstack stack build <stack> --activate-runtime

# force the next launch to use the runtime snapshot
hstack stack start <stack> --runtime

# temporarily bypass the runtime snapshot and run from source
hstack stack start <stack> --source

If you only rebuilt one component, remember that builds update artifacts, not the active runtime:

# new web artifact exists, but the runtime still serves the old UI until activation
hstack stack build <stack> --web
hstack stack runtime <stack> activate --web
# then reload the browser

# server/daemon partial activation still requires a restart
hstack stack build <stack> --server
hstack stack runtime <stack> activate --server
hstack stack service <stack> restart

“I changed something but nothing updates”

In dev mode, prefer running with --restart at least once (so hstack owns the PIDs and can restart safely):

hstack stack dev <stack> -- --restart

If you’re running hstack dev outside stack mode, do:

hstack dev --restart