Troubleshooting

Troubleshooting

Tool errors reach the client as MCP tool errors with the prefix Huly MCP:. The messages below are quoted from the code.

Login and credentials

Message	Cause	Fix
Missing credentials. Provide HULY_TOKEN (for SSO accounts) or both HULY_EMAIL and HULY_PASSWORD.	No auth variables reached the server process	Set them in the client's env block or .env (Docker). Empty values count as missing.
Login failed: no token returned. Check credentials. / an error from login	Wrong email/password, or no password set on the account	Set a password in Huly (Profile → Security) or use HULY_TOKEN
HULY_TOKEN is invalid or expired. Please get a fresh token (npm run setup).	Token expired or revoked	npm run setup, or switch to email + password
Token auth: no socialId returned for HULY_TOKEN.	Token not usable for login (e.g. incomplete)	Get a fresh token via npm run setup
Login works in the browser but not here (self-hosted)	HULY_ACCOUNTS_URL missing, so the server logs in at Huly Cloud	Set HULY_ACCOUNTS_URL (see Self-Hosted Huly)

Workspaces

Message	Cause	Fix
Multiple workspaces available — pass 'workspace' explicitly (see list_workspaces). Available: …	A read tool was called without workspace and the account has several	Pass workspace
Input validation error: … "path": ["workspace"] … "Required"	A writing tool was called without workspace	Always pass workspace for changes (by design, see Multi-Workspace)
Unknown workspace 'x'. Available: …	No workspace has that ID, slug or name (no prefix matching)	Use a value from list_workspaces
Workspace name 'x' is ambiguous — use the slug or ID instead: …	Two workspaces share that display name	Use the slug or ID
Workspace must not be empty (see list_workspaces).	workspace was "" or only spaces	Pass a real value
HULY_WORKSPACE='x' is not accessible. Available: …	The legacy filter matches no workspace of this account	Fix or remove HULY_WORKSPACE
list_workspaces shows only one workspace	HULY_WORKSPACE is set, or HULY_TOKEN is a workspace-scoped token and enumeration was refused	Remove HULY_WORKSPACE; use an account token from npm run setup
No Huly workspaces are accessible with these credentials.	The account belongs to no workspace	Join or create a workspace in Huly
Workspace 'x' not found or not accessible.	selectWorkspace returned no endpoint/token	Check the account's access to that workspace and its state in list_workspaces (disabled, mode)
selectWorkspace('x') returned workspace …, expected …	Account service returned a different workspace than discovered	Restart the server; report it if it persists
Huly connections were closed.	A call was in flight while the server shut down	Retry after restart

Content and files

Symptom	Cause	Fix
_(Set HULY_FRONT_URL env var to fetch …)_ in get_document/get_issue	HULY_FRONT_URL not set	Set it (Cloud: https://front.huly.app; self-hosted: your instance URL)
Content/description missing, no error	Front answered non-200 (e.g. 404 for a blob ref that isn't stored as a file, 401 for auth)	Check HULY_FRONT_URL; some collaborative descriptions (…-description-…) are not served by /files
Self-hosted file upload failed (401) at …/files	Wrong front URL or token not accepted	Check HULY_FRONT_URL points to the same instance as HULY_ACCOUNTS_URL
Datalake upload failed (…) on a self-hosted instance	HULY_FRONT_URL unset, so uploads went to Huly Cloud	Set HULY_FRONT_URL

Install and runtime

Symptom	Cause	Fix
npm error could not determine executable to run	npx huly-mcp-selfhost resolved to huly-mcp-selfhost@1.0.0, which has no huly-mcp-selfhost executable	Use 2.0.0 or later (npx -y huly-mcp-selfhost@latest); on 1.0.0 only npx -y --package=huly-mcp-selfhost huly-mcp works
Compose: The "HULY_WORKSPACE" variable is not set. Defaulting to a blank string.	docker-compose.yml still references ${HULY_WORKSPACE} after you removed it from .env	Harmless (blank = no restriction). Remove the reference from the compose file to silence it
First tool call in a workspace takes several seconds	The workspace model is loaded when its connection opens	Expected; later calls reuse the connection
stderr shows no document found, failed to apply model transaction, skipping …	Huly SDK diagnostics while loading the model	Harmless
❌ dist/ not found. Run npm run build first.	A helper script ran before building	npm run build
Helper script: ❌ No workspace given.	Scripts write data and need an explicit workspace	Add --workspace=<slug>
Docker: connection errors to Huly	Container can't reach accounts/WebSocket/front URLs (e.g. localhost)	See Docker Deployment

Still stuck?

Run the discovery check from a clone: npm run setup (see Setup wizard). Then open an issue or discussion on the repository.