Troubleshooting

Start with the log of the service that shows the symptom: docker compose logs <service>. For a server, run the same command in the server’s deploy/ directory.

Installation and start

Symptom	Cause	Fix
docker compose stops with set MCP_DOMAIN in .env (or required variable MCP_DOMAIN is missing a value)	.env does not exist or has no MCP_DOMAIN	Copy platform.env to .env and set MCP_DOMAIN. If you wrote .env with echo, check it with tail .env for a broken line.
init stops the start and names a reason in docker compose logs init	The certificate does not name the domain, the key does not fit it, or the chain does not verify against certs/company-ca.crt or a public CA	Fix certs/ as the message says and run docker compose up -d.
gateway-init prints warn broker ...: connection refused	The broker is still starting. This is normal on the first start.	Wait a few minutes.
After docker compose restart, gateway-init reports a failure but the platform works	restart restarts the one-shot gateway-init at the same time as Keycloak	Run docker compose up -d. It runs gateway-init again in order.
docker compose logs init ends with warn certificates or trust stores changed	init replaced a certificate or trust store on a running installation	Run the docker compose restart ... command that the warning prints.
nginx does not start, keycloak-config failed	The bootstrap administrator of the master realm already had an OTP before keycloak-config ran, so the one-time configuration could not sign in	Start nginx alone with docker compose up -d --no-deps nginx, do the steps of keycloak/configure.sh by hand in the Keycloak consoles (OTP for every master realm administrator, the password policy, brute force detection, the client roles of mcp-platform-admin), then run docker compose run --rm keycloak-config mark-done. See the mcp-platform README, “Install”.
Redirect from port 80 or addresses from the platform lose the port	https runs on a port other than 443 and MCP_PUBLIC_ORIGIN is not set	Set MCP_PUBLIC_ORIGIN=https://<domain>:<port> and run docker compose up -d.
The gateway Redis services cannot read their files	The gateway image is built before its group id was fixed and runs with gid 999	Use the gateway image from ghcr.io/aiwcorpo in the version the bundle names.
Compose tries to pull third-party images on an offline host	Docker Engine with the classic image store does not keep registry digests for loaded images	Add compose.offline.yaml to COMPOSE_FILE and set PULL_POLICY=never (offline install).
Shell scripts in the bundle fail on Windows	An editor or extractor rewrote the line endings to CRLF	Extract again and keep LF line endings.
The broker does not start after you removed openbao-keys from the host	OpenBao is sealed until someone unseals it	Unseal with bao operator unseal (Back up).

Sign-in and AI clients

Symptom	Cause	Fix
Claude Code shows the server as connected with no capabilities and no tools	Gateway 2.0.0 lacks ttlMs and cacheScope in the tool list for MCP 2026-07-28 (issue 1)	Upgrade the gateway to 2.0.1 (Upgrade).
Claude Code: ERR_CONNECTION_REFUSED on localhost:33418 (local setup)	Claude Code does not trust the local CA	Set NODE_EXTRA_CA_CERTS to the CA file in the same shell, then sign in again.
Browser warns about the certificate (local setup)	The system does not trust the local CA	Add the CA to the system certificate store (Install locally).
An administration action answers step_up_required	The sign-in is older than 5 minutes or has no second factor	Sign in again with the OTP.

MCP servers

Symptom	Cause	Fix
The server stops at start: cannot fetch the key set	The server host does not resolve <platform> or does not trust its certificate	Fix DNS. If a company CA signed the platform certificate, add it to the server’s trust store and uncomment JAVA_TOOL_OPTIONS (Install an MCP server).
Add server: tls_handshake_failed or manifest_unreachable	The server is not running, or port 8443 is closed between the platform host and the server host	Check docker compose ps on the server host and open the port to the platform host.
Add server: plain_http_not_allowed	An http:// address without “allow plain http”	Tick it, only for servers in the Docker network of the platform. Use https for servers elsewhere.
Add server: the address is refused	It resolves to a loopback, link-local (including 169.254.169.254), unspecified or multicast address	Use the real address of the server. Local test: host.docker.internal (Install locally).
Server status certificate_changed	A pinned server presents a new certificate, for example after its state volume was recreated	Compare the new fingerprint and approve it in the portal.
Tool call: upstream_unavailable, the server log has SSLHandshakeException	The server’s trust store lacks the CA of the backend system, or JAVA_TOOL_OPTIONS is commented out	Import the CA, then docker compose up -d --force-recreate on the server host.
Tool call: upstream_unavailable, server status unreachable	The server does not answer on its address	Check the address, the port and the server log.
Tools of a server are missing, its policies are pending_approval	A new or changed policy waits for approval	Approve it in Administration (Servers).
Saving a token in the portal: “service temporarily unavailable”	The broker does not trust the CA of the system	Add that CA to certs/company-ca.crt, run docker compose up -d, then the restart command from docker compose logs init | grep warn.
Local setup: server cannot fetch keys	compose.override.yaml has no extra_hosts for mcp.localhost, the trust store lacks the local CA, or JAVA_TOOL_OPTIONS is commented out	Redo steps 3.2 to 3.4 of Install locally.
Local setup on Linux: the gateway cannot reach host.docker.internal	The name is not defined on Linux	Add extra_hosts: ["host.docker.internal:host-gateway"] for gateway.

Problems specific to one server (version limits of Jira and Confluence, OpenSearch roles, the service desk layout) are in the “Common problems” section of its deploy README, linked from Install an MCP server.