From 32abd1d848bdb6a844734d11053577177096a5aa Mon Sep 17 00:00:00 2001 From: Kailas Mahavarkar <66670953+KailasMahavarkar@users.noreply.github.com> Date: Fri, 10 Apr 2026 17:31:53 +0530 Subject: [PATCH] docs(install): add troubleshooting section for common MCP failures Covers private Docker image (unauthorized pull), server not starting, SessionStart hook not firing, and missing Bun. Includes direct link to GitHub package visibility docs for the ghcr.io private-by-default issue. Co-Authored-By: Claude Sonnet 4.6 --- install.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/install.md b/install.md index d4303d1..effbc9e 100644 --- a/install.md +++ b/install.md @@ -105,3 +105,33 @@ Tell the user: 5. Which verification step they should run first If installation failed at any step, report the specific error and what would need to be fixed, rather than claiming success. + +## Troubleshooting + +### MCP server shows as failed / `unauthorized` when pulling the Docker image + +This means the Docker image is private. The image at `ghcr.io/orkait/hyperstack:main` must be set to public for unauthenticated pulls to work. + +To fix: +1. Go to [github.com/orgs/orkait/packages/container/hyperstack](https://github.com/orgs/orkait/packages/container/hyperstack) +2. Click **Package settings** +3. Under **Danger Zone**, click **Change visibility** +4. Set to **Public** +5. Re-run `docker pull ghcr.io/orkait/hyperstack:main` to verify + +Reference: [GitHub Docs - Configuring a package's access control and visibility](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility) + +### MCP server starts but tools return no results + +The MCP config file may point to the wrong binary or the server is not running. Verify: +- Docker: run `docker run -i --rm ghcr.io/orkait/hyperstack:main` and confirm it starts without error +- Local Bun: confirm the absolute path in `args` exists (`ls /path/to/hyperstack/bin/hyperstack.mjs`) +- Restart the CLI/IDE after any config change - MCP servers are loaded at startup + +### SessionStart hook does not fire + +On Claude Code, hooks live in `.claude/hooks.json`. Confirm the file exists in the repository root and references `session-start.mjs`. If the hook is missing or malformed, the `using-hyperstack` skill will not be injected automatically. You can still invoke skills manually with `/using-hyperstack`. + +### `bun: command not found` when using Option B + +Install Bun: `curl -fsSL https://bun.sh/install | bash`, then open a new shell so the path update takes effect.