./pipeshub by default). If you changed COMPOSE_PROJECT_NAME, use that instead of pipeshub-ai.
First checks
3000 with your APP_PORT if you changed it.
Install and start
White or blank screen after deploying to a server
White or blank screen after deploying to a server
You are opening PipesHub over plain HTTP from a hostname. Browsers block features PipesHub needs unless the page is on HTTPS or
localhost. Put a TLS-terminating reverse proxy in front of it and set the public HTTPS URL. See Serving it over HTTPS.Cannot access the Docker socket
Cannot access the Docker socket
Your user is not in the or run the installer with
docker group. Either add it and log in again:sudo.Insufficient CPU cores
Insufficient CPU cores
The installer stops on fewer than 4 cores. Use a larger machine. See System Requirements.
Low RAM warning
Low RAM warning
slim and full want a 16 GB-class machine. On an 8 GB machine, use the eval type:Health check did not pass in time
Health check did not pass in time
The installer waits 420 seconds. The first start of a
slim image downloads the embedding model, which can take longer on a slow connection. Wait a few minutes and run the health check above. To wait longer next time, set HEALTH_WAIT_SECS.A container keeps restarting (exit 137)
A container keeps restarting (exit 137)
Exit code 137 means the container was killed, usually for running out of memory. Check it:Free memory, or move to the lighter
slim type, which drops Kafka and Zookeeper: ./install.sh --reconfigure. For MongoDB, raise MONGO_CACHE_GB and MONGO_MEMORY_LIMIT together.MongoDB keeps restarting (exit 139)
MongoDB keeps restarting (exit 139)
MongoDB 8 can crash on some newer host kernels. The installer normally detects this and fixes it. If not, set this in Do not delete the MongoDB volume to fix this. That destroys your data and does not fix the cause.
.env and run ./install.sh --upgrade:Port 3000 is already in use
Port 3000 is already in use
The installer moves to the next free port and prints the one it chose. To pick one yourself, set
PIPESHUB_PORT.The container cannot reach the internet
The container cannot reach the internet
Cloud AI models and most connectors need outbound access; local models do not. Test it:If
/etc/docker/daemon.json contains "iptables": false, Docker is not routing container traffic. Remove that setting and restart Docker.First-run setup stops with "Scopes not allowed for this app: code:read"
First-run setup stops with "Scopes not allowed for this app: code:read"
MCP_SCOPES is set in .env without code:read. Add it, or remove the line to use the default. See Upgrading to 1.0.Services stop at startup after changing VECTOR_COLLECTION_STRATEGY
Services stop at startup after changing VECTOR_COLLECTION_STRATEGY
That setting cannot be changed on an existing install, because the vectors are already stored in the old layout. Set it back.
Signing in and the API
Someone cannot sign in after upgrading to 1.0
Someone cannot sign in after upgrading to 1.0
SAML and generic OAuth sign-in are not in the open-source edition. See Authentication for how those people set a password.
The right password is rejected
The right password is rejected
After 5 wrong passwords or codes in a row, the account is locked for 24 hours, and sign-in shows the ordinary “incorrect” message. See Authentication.
429 Too many requests
429 Too many requests
A rate limit was reached. Wait for the number of seconds in the
Retry-After header. If everyone behind a reverse proxy hits the limit at once, set TRUST_PROXY. See Rate Limits and API Errors.An API error has a requestId
An API error has a requestId
Search the app logs for it to find the cause:
Indexing
Indexing is slow and the CPU is idle
Indexing is slow and the CPU is idle
The app sizes indexing and parsing from its memory limit. A container held near its limit runs only a couple of documents at a time. Raise
APP_MEMORY_LIMIT (and APP_MEMSWAP_LIMIT with it) if the machine has free memory. See Environment Variables.Search is slow on a large index
Search is slow on a large index
Qdrant slows down once the index no longer fits in
QDRANT_MEMORY_LIMIT (default 6 GB). Raise it.