Fix LibreChat MCP Stuck: Docker UID/GID Warnings Guide

The repeated “The "UID" variable is not set” messages come from Docker Compose interpolating ${UID}:${GID} in LibreChat’s docker-compose and are usually harmless for startup, but they can cause file-permission mismatches on mounted volumes; fix them by writing numeric UID/GID values into a .env file. The “Creating new instance” line is a normal MCP startup message — if nothing follows, the MCP process is likely waiting for required ClickHouse settings or network/credential access (missing CLICKHOUSE_HOST/PORT/USER/PASSWORD), not the UID/GID warnings. Add numeric UID/GID to .env, confirm ClickHouse connectivity and required MCP env vars, then restart and re-check logs.

Contents

• UID/GID warnings (docker uid gid)
• Where to define UID and GID
• Why MCP server hangs at “Creating new instance” (librechat mcp server)
• Recommended UID/GID configuration examples (mcp server docker)
• Step‑by‑step troubleshooting checklist
• Sources
• Conclusion

UID/GID warnings (docker uid gid)

Those WARN lines come from Compose because the Compose file references user: "${UID}:${GID}" for services (api, mongodb, meilisearch) but those variables are unset. You can see that pattern in LibreChat’s compose file: the repo uses user: "${UID}:${GID}" in multiple services (see the file on GitHub) — when Compose finds an unset variable it warns and substitutes an empty string by default: https://raw.githubusercontent.com/danny-avila/LibreChat/main/docker-compose.yml.

Are the warnings fatal? Usually no. Docker Compose will still start containers; the warnings themselves don’t abort startup. But they matter because a missing UID/GID can cause the container to run as the image’s default user (often root or some internal app user), and that can create files owned by a different UID on host-mounted volumes — leading to permission problems later. StackOverflow and Compose docs show the same behavior: unset env vars produce warnings and blank defaults; the usual fix is to provide numeric UID/GID values so ownership lines work as intended: https://stackoverflow.com/questions/56844746/how-to-set-uid-and-gid-in-docker-compose.

Quick checks

• Confirm the user: lines in your compose: grep -n "user:" docker-compose.yml.
• See the effective user inside the running API container: docker compose exec api id (or docker compose exec api id -u; docker compose exec api id -g).

Where to define UID and GID

Best practice: put numeric UID and GID in your project .env file so Compose picks them up automatically. LibreChat docs and the compose examples expect UID/GID to be present in the environment (.env is the conventional place): https://docs.librechat.ai/install/providers/mcp_servers.html and the repo examples show the interpolation usage https://github.com/danny-avila/LibreChat/blob/main/docker-compose.yml.

Important detail: Compose does not execute shell substitutions inside .env. That means you shouldn’t literally write UID=$(id -u) inside .env and expect Compose to run it. Instead, run the shell command while creating the file so .env contains the numeric values. Example (run this on your Ubuntu VM from the LibreChat directory):

# create or overwrite .env with your numeric UID/GID and some MCP vars
printf "UID=%s\nGID=%s\n" "$(id -u)" "$(id -g)" > .env
cat >> .env <<'EOF'
# example ClickHouse/MCP settings — adjust as needed
CLICKHOUSE_HOST=clickhouse
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=changeme
PORT=4200
EOF

Alternatives

• Export in the shell before launching Compose: export UID=$(id -u) && export GID=$(id -g) && docker compose up -d. Compose will read environment variables present in the process environment.
• Hardcode numeric user: "1000:1000" in docker-compose.yml for quick debugging (less flexible, not recommended for multi-user hosts).

Why .env is preferred: one place to manage config, safe to commit (if you remove secrets) or add to .gitignore, and Compose automatically loads it.

Source references: LibreChat docs and compose examples: https://docs.librechat.ai/install/providers/mcp_servers.html and https://raw.githubusercontent.com/danny-avila/LibreChat/main/docker-compose.yml.

Why MCP server hangs at “Creating new instance” (librechat mcp server)

“Creating new instance” is a startup message from the MCP registry — not necessarily an error. The ClickHouse MCP implementation and LibreChat docs both mention that this line is shown during initialization; if the process stalls there, the usual causes are missing/incorrect MCP-specific environment variables (ClickHouse host/port/credentials) or network/connectivity problems rather than the UID/GID warnings: https://github.com/ClickHouse/mcp-clickhouse and https://docs.librechat.ai/install/providers/mcp_servers.html.

Common root causes

• CLICKHOUSE_HOST or CLICKHOUSE_PORT is unset or pointing to the wrong service name.
• CLICKHOUSE_USER / CLICKHOUSE_PASSWORD are missing (auth failure) or an incorrect transport/URL is used.
• The ClickHouse container/service isn’t healthy or not reachable on the expected network/port.
• DNS/service name mismatch (service is named clickhouse in compose but your CLICKHOUSE_HOST points somewhere else).

What you should do next

• Tail the API logs (full output, not just MCP grep): docker compose logs -f api --tail=200 and watch for errors following “Creating new instance”.

• Tail the ClickHouse service logs: docker compose logs -f clickhouse --tail=200. A healthy ClickHouse will show startup OK; an unhealthy one will report errors.

• Test connectivity from the API container to ClickHouse (replace clickhouse with your host if different):

• If the ClickHouse image provides a client:
  docker compose exec clickhouse clickhouse-client --query "SELECT 1"

• From the API container (if it has curl/nc):
  docker compose exec api sh -c 'curl -sS http://clickhouse:8123/' || true

• Check LibreChat health endpoint (if exposed): curl -f http://localhost:4200/health — the ClickHouse mcp repo suggests using /health to verify the service: https://github.com/ClickHouse/mcp-clickhouse.

Note: The UID/GID warnings will usually not prevent the MCP from completing instance creation; they’re orthogonal concerns. Fix both, but prioritize ClickHouse envs and connectivity for the stuck MCP.

Recommended UID/GID configuration examples (mcp server docker)

Minimal .env (create it with numeric UID/GID from your VM user):

# run this in the project directory:
printf "UID=%s\nGID=%s\n" "$(id -u)" "$(id -g)" > .env
cat >> .env <<'EOF'
PORT=4200

# ClickHouse MCP settings — adjust to your compose/service names
CLICKHOUSE_HOST=clickhouse
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=changeme
EOF

Example docker‑compose service snippet (keep the repo’s user: "${UID}:${GID}" pattern):

services:
 api:
 image: librechat/api:latest
 user: "${UID}:${GID}"
 environment:
 - CLICKHOUSE_HOST=${CLICKHOUSE_HOST}
 - CLICKHOUSE_PORT=${CLICKHOUSE_PORT}
 - CLICKHOUSE_USER=${CLICKHOUSE_USER}
 - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD}
 depends_on:
 - clickhouse

Notes and extra steps

• If any existing volumes contain files owned by root (or another UID), you may need to chown them on the host so the new UID/GID can write/read correctly:

sudo chown -R "$(id -u):$(id -g)" ./data || true

• If you change UID/GID and things still behave oddly, bring Compose down and optionally remove anonymous volumes (careful: data loss):

docker compose down
# only if you understand the data loss risk:
docker compose down -v
docker compose up -d

• For a quick debug: temporarily remove or comment the user: lines so containers run as the image default user; that can show whether permission bits were actually blocking initialization. Don’t leave that in production.

Reference examples and suggestions in the ClickHouse MCP project and LibreChat docs: https://github.com/ClickHouse/mcp-clickhouse and https://docs.librechat.ai/install/providers/mcp_servers.html.

Step‑by‑step troubleshooting checklist

1. Confirm UID/GID warnings and the compose file reference:

• grep -n "user: .*UID" docker-compose.yml || true
• cat .env | sed -n '1,50p'

2. If UID/GID missing — create .env with numeric values:

• printf "UID=%s\nGID=%s\n" "$(id -u)" "$(id -g)" > .env

3. Add ClickHouse MCP vars if missing:

• Append CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD to .env.

4. Restart the stack:

• docker compose down && docker compose up -d
• If you changed owner of volumes, consider docker compose down -v only if you can re-create data.

5. Tail logs (look beyond the single “Creating new instance” line):

• docker compose logs -f api --tail=200
• docker compose logs -f clickhouse --tail=200

6. Test services:

• LibreChat health: curl -f http://localhost:4200/health
• ClickHouse: docker compose exec clickhouse clickhouse-client --query "SELECT 1" or curl -sS http://localhost:8123/

7. Verify container user / filesystem permissions:

• docker compose exec api id
• docker compose exec api ls -ln /app (numeric owners shown)
• On host: sudo chown -R "$(id -u):$(id -g)" ./data

8. If stuck after these checks:

• Search API logs for CLICKHOUSE-related error messages: docker compose logs api | grep -i clickhouse || true
• Enable more verbose logging (set LOG_LEVEL=debug in .env) and restart to capture more context.
• If everything looks correct but the MCP still stalls, paste the full API and ClickHouse logs (not filtered grep) into an issue and include your .env (redact secrets) and docker-compose.yml — start with the ClickHouse MCP repo guidance: https://github.com/ClickHouse/mcp-clickhouse.

Sources

1. https://raw.githubusercontent.com/danny-avila/LibreChat/main/docker-compose.yml
2. https://github.com/ClickHouse/mcp-clickhouse
3. https://docs.librechat.ai/install/providers/mcp_servers.html
4. https://stackoverflow.com/questions/56844746/how-to-set-uid-and-gid-in-docker-compose
5. https://github.com/danny-avila/LibreChat/blob/main/docker-compose.yml
6. https://www.librechat.ai/docs/local/docker
7. https://hub.docker.com/r/mcp/clickhouse

Conclusion

Fix the docker uid gid warnings by adding numeric UID/GID to a .env (or exporting them before docker compose up), then focus on ClickHouse connectivity and MCP-specific env vars — those are the usual causes when LibreChat’s MCP server remains stuck at “Creating new instance”. After applying the .env change, restart the stack and tail the API and ClickHouse logs; if connectivity and credentials are correct the MCP should proceed.