Skip to content

troubleshooting.md

Latest commit

 

History

History
130 lines (80 loc) · 3.21 KB

troubleshooting.md

File metadata and controls

130 lines (80 loc) · 3.21 KB
Raw

Troubleshooting

The plugins do not appear in Codex UI

Check these items in order:

  1. Confirm the marketplace is registered in ~/.codex/config.toml
  2. Confirm gitlab-mcp@codex-api-plugins and km-confluence-drawio@codex-api-plugins are enabled in the same file
  3. Confirm the marketplace source points to your current local clone
  4. Fully restart Codex Desktop

If you used the installer script, rerun it once:

powershell -ExecutionPolicy Bypass -File .\scripts\install-home-local.ps1

python is missing for km-confluence-drawio

Install Python and verify:

python --version

This plugin expects Python 3.11+ because the KM MCP shim uses tomllib.

npx is missing

Install Node.js and verify:

npx --version

gitlab-mcp and the draw.io MCP server both depend on npx.

gitlab-mcp reports invalid_token

Your GitLab token is missing, expired, or not inherited by the current Codex session.

Check:

  1. GITLAB_PERSONAL_ACCESS_TOKEN is set at the user or machine scope
  2. The token has not expired in GitLab
  3. Codex Desktop was restarted after the variable changed

gitlab-mcp cannot connect to the server

The most common cause is a bad GITLAB_API_URL.

Use this format:

[Environment]::SetEnvironmentVariable('GITLAB_API_URL', 'https://gitlab.example.com/api/v4', 'User')

Checks:

  • use the GitLab base URL for your instance
  • include /api/v4
  • do not use a project or merge request web URL here

gitlab-mcp can read but cannot write

This usually means the token only has read_api scope.

For draft review notes or publish flows, use a token with:

  • api

If you only want read-only inspection, read_api is enough.

km-mcp says CONFLUENCE_URL or CONFLUENCE_PERSONAL_TOKEN is not configured

In this repository, CONFLUENCE_URL already defaults to Lenovo KM. In practice this usually means:

  • CONFLUENCE_PERSONAL_TOKEN is missing
  • Codex was not restarted after the token changed
  • you intentionally overrode CONFLUENCE_URL with an empty or bad value

Set the token again and restart Codex:

[Environment]::SetEnvironmentVariable('CONFLUENCE_PERSONAL_TOKEN', '<your-km-token>', 'User')

km-mcp returns 401 or 403

Your token is invalid, expired, or does not have access to the page or space you asked for.

Check:

  1. The token value is correct
  2. The token still works in Lenovo KM
  3. The target page is inside the spaces your account can read

km-mcp search returns fewer pages than expected

The most common cause is CONFLUENCE_SPACES_FILTER.

If you set:

[Environment]::SetEnvironmentVariable('CONFLUENCE_SPACES_FILTER', 'DCIM', 'User')

then KM reads are intentionally limited to DCIM. Clear or broaden that variable if you want wider results.

The draw.io server does not start

Check npx first:

npx --yes @next-ai-drawio/mcp-server@0.4.13 --help

If this fails:

  • confirm Node.js is installed and on PATH
  • confirm the current machine can fetch npm packages
  • retry after clearing any corporate proxy or registry issue

How to validate the repository after changes

Run:

powershell -ExecutionPolicy Bypass -File .\scripts\validate-repo.ps1