Troubleshooting¶

English | 日本語

A Skill or tool is missing¶

Start a new Codex session after installing or updating the Plugin. Use the installed plugin-diagnostics Skill to inspect manifest, provenance, explicit update status, and MCP health. Do not repair an installed copy by editing its cache.

A marketplace refresh leaves the old version installed¶

An exact-ref marketplace stays on its reviewed immutable commit when a generic marketplace refresh runs. This is expected; a successful refresh is not evidence that the pin advanced. Follow the complete exact-ref update journey: detect and review the target, run the packaged updater preflight from a stable directory, authorize and execute the exact transition, verify version/enabled/ release/provenance state, and start a new session.

If the updater reports rejected, use its required action; it made no update effect. If it reports rolled-back, retain the failure evidence and verify the restored exact identity in a new session. If it reports unresolved, do not retry or improvise a remove/add sequence—inspect the exact marketplace and Plugin state before any further effect. Never hand-edit config.toml, marketplace JSON, or the installed cache.

A GitHub operation cannot run¶

Confirm repository identity, authentication, and permissions in the selected provider. AI Teams fails to a supported fallback only after the earlier provider has an explicit unavailable, unauthorized, or unsupported observation. It does not invent success or silently change the system of record.

Validation does not pass¶

Keep the failed evidence. Fix the candidate when its checks failed, or restore the isolated self-hosted runner/workflow when execution was unavailable. Merge requires a new exact-head hosted validate success; no local result or skipped check is a waiver.

Worktree validation stalls on a Windows-mounted WSL path¶

AI Teams worktree readiness and CI preflight require Linux-native filesystem semantics. A repository or worktree under a Windows-mounted path such as /mnt/c or /mnt/d can stall in DrvFS/9P operations; moving only the Issue worktree to a Linux-native filesystem avoids that supported-path mismatch.

Linux-native does not mean that the worktree must use literal /home or that the WSL virtual disk must remain on the Windows system drive. The distribution's VHDX consumes space on whichever Windows drive stores it. If capacity is a concern, follow Microsoft's current WSL distribution relocation guidance instead of moving the worktree back to DrvFS/9P. The relocation procedure is Microsoft-owned and includes destructive steps, so verify its backup and version prerequisites there before changing the host.

For installation and MCP details, use the machine-facing diagnostic contract.