Canonical guide · Source docs/troubleshooting.md

Troubleshooting

Start with the symptom you see. Do not delete or rebuild n8n while you check the sidecar. Keep a working manual OAuth sidecar until the wizard-managed endpoint passes a real n8n request.

Always keep a current export or backup of your n8n workflows before using the wizard or any manual VPS command. The documented commands are sidecar-only and do not delete, restart, or rebuild n8n, but they still access your VPS and write files there.

Docker is not running

Start Docker Desktop or Docker Engine and wait until docker info and docker compose version both succeed. Close any stale Relmio wizard tab, start one fresh wizard session, and review the local plan again. Do not restart or rebuild unrelated containers while checking the local endpoint.

Authentication fails

Close stale wizard and device-code tabs, then run relmio open from a persistent install to open the active private dashboard page. A hosted foreground launcher instead requires its current terminal; press Enter there to create a fresh private browser handoff. Start one fresh ChatGPT device-code attempt and complete the newest code. Use the selected provider's official sign-in. Relmio 0.14.0 does not accept upstream API keys. Grok Build sign-in uses its official attended CLI flow. ChatGPT/Codex sign-in tokens expire, but the official Codex client refreshes them automatically during active use before they expire, so active sessions usually continue without another browser login. The official OpenAI authentication documentation does not publish a fixed 10-day lifetime; do not plan around one. This provider credential is separate from Relmio's local capability, which remains valid until you rotate it. If Relmio reports the credential is invalid or refresh no longer succeeds, select Start ChatGPT sign-in again in the active local wizard. The VPS sidecar flow labels that action Refresh ChatGPT sign-in.

Local image build failed

The local wizard intentionally does not show Docker build output, filesystem paths, or stderr in the browser. Confirm Docker Desktop or Docker Engine is running, check that the local disk has room for the image, and confirm your network can reach the image registry. Then close the old wizard, start one new wizard session, review a fresh plan, and retry. Do not delete an existing managed endpoint or rebuild unrelated containers as a workaround.

Hosted chat browser extension

The hosted demo at relmio.jpfusin.tech needs the open-source Sign in with ChatGPT extension to complete the OAuth handoff:

• Install for Chrome
• Install for Firefox

After installation, reload Relmio and select Connect ChatGPT again. If the chat still shows Not connected, confirm the extension is enabled, close stale ChatGPT authorization tabs, and start one fresh connection from Relmio. The hosted sign-in component also displays its extension install screen when it detects that the extension is missing.

This requirement applies to the hosted chat, not the local npm wizard. The wizard listens directly on localhost:1455; if an OAuth extension captures that local callback, temporarily disable it during local sign-in and re-enable it after the wizard saves the credential.

Confirm the local package first

Close every old wizard terminal and browser tab, then run the newest published build on your own computer, not on the VPS. Choose the command for the terminal you already have.

macOS, Linux, WSL, or Git Bash:

curl -fsSL https://relmio.jpfusin.tech/install.sh | sh

Homebrew (macOS or Linux):

brew tap Demonbane18/relmio && brew trust --formula Demonbane18/relmio/relmio && brew install relmio

Windows PowerShell:

irm https://relmio.jpfusin.tech/install.ps1 | iex

Windows Command Prompt:

for /f "delims=" %F in ("%TEMP%\relmio-install-%RANDOM%-%RANDOM%-%RANDOM%.cmd") do @if exist "%~F" (exit /b 80) else curl -fsSL --remove-on-error https://relmio.jpfusin.tech/install.cmd -o "%~F" && set "RELMIO_SELF_DELETE=%~F" && call "%~F"

These commands do not require Node.js to be installed. The native Windows options do not require Git Bash and reuse Node.js 24 or newer when available. Git Bash always uses a verified temporary runtime through its bundled winpty bridge so the native Node child receives terminal handles. Every portable path shows staged Please wait messages while it downloads, verifies, and extracts the official runtime. The Command Prompt bootstrap itself does not call PowerShell, request elevation, or change Windows security policy.

After either Windows bootstrap starts Relmio, the running wizard uses the inbox Windows PowerShell security API to apply and verify owner-only NTFS protection before writing local credentials. Every native Windows launcher shares this check. If an organization blocks the inbox tool or its security API, setup stops before saving secrets; changing launch commands does not bypass the check. macOS and Linux protect the same managed paths with POSIX permissions instead.

Homebrew is available from the public Demonbane18/relmio tap. Homebrew's Tap Trust model requires an explicit trust decision for third-party formulae; this command scopes that decision to Demonbane18/relmio/relmio only. It does not trust the whole tap or disable a global safety control. The WinGet command stays hidden until Microsoft accepts its catalog pull request and the catalog updates. Until then, use Homebrew or one of the direct bootstrap commands on this page.

If you choose the existing-Node fallback, confirm Node is version 24 or newer and check the published package version first:

node --version
npm view relmio version
npx --yes --ignore-scripts relmio@latest

Homebrew and direct npm or NPX runs use the persistent dashboard. After a Homebrew or global npm install, run relmio status and relmio open. Without a global install, use the full NPX lifecycle commands:

npx --yes --ignore-scripts relmio@latest status
npx --yes --ignore-scripts relmio@latest open
npx --yes --ignore-scripts relmio@latest stop

The hosted curl, PowerShell, and Command Prompt launchers run in the foreground. Keep that terminal open. If the first browser launch fails, press Enter there to create a fresh owner-only, single-use browser handoff. Relmio does not print or pass the dashboard session capability in a browser URL.

The local wizard may be displayed in a VS Code embedded browser. Its validated manual link, Open fresh ChatGPT sign-in, remains available if that embedded browser blocks the popup or no new tab opens. Use that link only from the active wizard attempt; it points to the fresh auth.openai.com authorization URL.

You do not need to sign in to npm, configure npm 2FA, or own this package to run any public command. npm authentication is required only for the maintainer who publishes a release.

Quick VPS checks

On the VPS:

docker compose \
  --project-name n8n-openai-oauth \
  --file /docker/n8n-openai-oauth/docker-compose.yml \
  ps

docker compose \
  --project-name n8n-openai-oauth \
  --file /docker/n8n-openai-oauth/docker-compose.yml \
  logs --tail=50 openai-oauth

Check whether Docker published the sidecar port:

docker compose \
  --project-name n8n-openai-oauth \
  --file /docker/n8n-openai-oauth/docker-compose.yml \
  port openai-oauth 10531

Success is no output. 10531/tcp shown in docker ps without a host address is only an internal container port. A value such as 0.0.0.0:10531 or 127.0.0.1:10531 is a real host mapping and must be investigated rather than bypassed.

Symptom table

Check the OAuth file safely

Do not run cat on the file. Check only its metadata:

ls -ldn /docker/n8n-openai-oauth/auth
ls -ln /docker/n8n-openai-oauth/auth/auth.json

Expected:

auth directory: owner 1000, group 1000, mode drwx------
auth.json: owner 1000, group 1000, mode -rw-------

Fix on the VPS:

chown 1000:1000 /docker/n8n-openai-oauth/auth
chmod 700 /docker/n8n-openai-oauth/auth
chown 1000:1000 /docker/n8n-openai-oauth/auth/auth.json
chmod 600 /docker/n8n-openai-oauth/auth/auth.json

Check the mount

docker inspect n8n-openai-oauth-openai-oauth-1 \
  --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

Expected:

/docker/n8n-openai-oauth/auth -> /home/node/.codex

The generated container name can differ. Find it with:

docker compose \
  --project-name n8n-openai-oauth \
  --file /docker/n8n-openai-oauth/docker-compose.yml \
  ps

Check the shared network

docker inspect n8n-n8n-1 \
  --format '{{range $name, $_ := .NetworkSettings.Networks}}{{println $name}}{{end}}'

docker inspect n8n-openai-oauth-openai-oauth-1 \
  --format '{{range $name, $_ := .NetworkSettings.Networks}}{{println $name}}{{end}}'

At least one name must match. For the Hostinger setup used during development, that name was proxy.

Check from n8n without installing curl

Do not modify the n8n image merely to add a diagnostic tool. Use Node if it is available in the n8n container:

docker exec n8n-n8n-1 \
  node -e 'fetch("http://n8n-openai-oauth:10531/v1/models").then(async (response) => { console.log(response.status); console.log(await response.text()); }).catch((error) => { console.error(error.message); process.exit(1); })'

This is a read-only diagnostic request; it does not install anything or restart n8n.

Responses API setting

Use the switch that matches the provider:

• OpenAI OAuth/Codex recipe: leave Use Responses API on in OpenAI Chat Model node version 1.3. Earlier node versions do not show the switch and use Chat Completions by default. The bridge supports both routes.
• SuperGrok: turn Use Responses API off in workflow model nodes and Chat Hub. The companion supports Chat Completions, not /v1/responses. Its Assistant custom endpoint is configured separately.

For the OpenAI OAuth bridge, turn the switch off only as a temporary compatibility test if:

• /v1/models works;
• the node is definitely calling the correct Base URL; and
• the error specifically concerns /v1/responses.

If chat completions work but Responses does not, record the n8n version, node version, bridge logs, and sanitized error before changing anything else.

For a bridge installed before the current compatibility runtime, update the owned sidecar first. In the local dashboard use Manage bridge, then confirm the runtime update before choosing Update bridge runtime. For a VPS bridge, reconnect through relmio vps, verify the host fingerprint, select the n8n container and network, choose OpenAI-OAuth/Codex bridge, then Manage OpenAI-OAuth/Codex bridge. Select Review bridge update, review and confirm the plan, then choose Update the bridge. A package or source update by itself does not change a running sidecar.