Troubleshooting plugin connections

Back to the Codex learning hub

Goal and preparation

Lessons and resources mentioned here: Plugin setup

Step 1: Preserve the failure record

Record date, OS, surface, version, plugin name/source, sign-in method and failing step. Use this format on Windows/macOS/Linux. Check CLI version in a terminal and desktop version in app information or updates. Record local and remote hosts separately: desktop installation does not prove CLI installation. Use actual versions, not the article's date.

codex --version

# Plugin incident
Date and time zone:
OS / surface / version:
Local or remote host:
Plugin name and source:
Sign-in method (no secrets):
Failing step:
Exact error (redacted):
Practice document revision:
Change attempted:
Retest result:

Redact emails, private document IDs, tokens and cookies from shared errors. Never include authentication URLs containing one-time codes. Retain error type, time and reproduction; use provider support for server logs. Change one condition per retest to distinguish account, session and permission effects.

Step 2: Choose a layer by symptom

These are diagnostic steps, not guaranteed code mappings. Interpret provider responses: 401 often concerns authentication, 403 access, while missing files or changed sharing may produce similar errors. For 429/outages, follow returned retry guidance and retry the same small document later. Do not flood requests or make the drive public.

Step 3: Check surface, installation and enablement

On desktop inspect Plugins, Installed and details. In CLI, start codex, enter /plugins, check marketplace and entry; Space toggles an installed plugin. After installing or enabling, test a fresh task because old tasks may retain earlier capabilities. Keep their results; do not delete tasks or clear Codex configuration.

/plugins

Plugins are unsupported in IDE; test desktop or CLI. iOS/Android Chat/Work only use available plugins; Desktop only cannot run on mobile. Linux preview and individual plugins may impose conditions. Record unsupported surfaces instead of reinstalling. See Cross-device workflow.

Step 4: Separate account and document access

Open the source document with the plugin's external account and verify title/Revision. Another browser account's access proves nothing about this account. For a mismatch, use reconnection and retry the same URL in a fresh task. For document-specific denial, check sharing with its owner; grant only necessary access to your practice file.

ChatGPT subscription sign-in differs from OpenAI API key sign-in; some plugins requiring OAuth are unavailable with API key authentication. Check plugin details and Accounts. Do not put a service password in config.toml or use unrestricted approvals to solve OAuth. Host sandboxing governs local work, while the external service governs document access; relaxing one layer does not guarantee access through the other.

Step 5: Retest with an actual tool result

Use the selected plugin to read my practice document at <PRACTICE_DOCUMENT_URL>.
Return its title, source link, Revision, Document marker and task counts.
Use a fresh tool result. If access fails, report the tool error and stop.
Do not edit, share, move or delete anything. Do not infer missing contents.

Replace the placeholder URL and select the plugin/capability. Inspect actual tool activity; compare title, source, Revision, marker and counts against the original. No tool call means checking availability; a denied call means preserving that error, not reconstructing an answer from old conversation.

Manually change Revision and one count at the source without telling Codex the value. Use the same prompt in a fresh task. If stale, check copied URLs, saved edits and supported reread options; record delay. A correct retry verifies only this document and surface.

Diagnosis exercise: three different read failures

A: try a fresh desktop/CLI task; IDE lacks plugin support and connection success is unknown. B: check URL, account and sharing; change only authorized practice access. Reinstalling grants no document rights. C: compare source URLs, then record reread time/revision; do not guess memory or caching. Retest the same private document.

If the only evidence is the agent saying “success”, leave actual reading unconfirmed. Conversely, a tool that returned a denial was called and failed; do not label it “not loaded”. Using these distinctions in the incident record helps the next person inspect the correct surface or service.

Common failures and recovery

If Uninstall is absent, check whether the plugin is workspace-installed or a default managed by an administrator and record the restriction. Uninstalling removes that environment's bundle; separately connected MCP integrations can remain. To close the exercise, check both Installed and external connection management, revoking your practice authorization if needed. Preserve shared connections and do not equate one disconnection with disabling every device.

Restore the one changed condition: enable the plugin, reconnect the intended account or restore practice access. If a fresh task still fails, give the maintainer surface, plugin source, redacted error, attempted change and expected/actual results. Avoid repeated reinstalls. Use MCP troubleshooting for server configuration, distinct from plugin-directory issues.

Acceptance and next step

Keep original failure, identified layer, one change, fresh same-document result, input preservation and retained/revoked connection state. Without a tool result, report a surface limitation or pending authentication. These operations are documented, not tested on your account, OAuth flow or physical phone; article rendering does not prove connectivity.

Keep this record separate from Skill acceptance: loading a skill does not establish connection to its backing service. Reuse the fields from Templates and cheatsheets, updating observed values while retaining dates and unreproduced cases.

Back to the Codex learning hub

Read the full description

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI tools
• Tutorials
• Codex