Codex Skin troubleshooting

Start with the current local state, not an old Codex conversation. A previous Apply can be complete, failed, or interrupted while the current window has a different state. The Status Skill reports the durable facts that are safe to use for the next decision.

Check current Status first

Ask Codex Skin to read local status:

Codex Skin, show my local theme status.

Status does not call the network. It can report:

whether a local device reference exists;
a pending six-digit theme ID;
the last package whose one-time operation committed after visible verification; and
a bounded restart kind, status, and stable error code when present.

Read those fields narrowly. deviceLinked: true does not prove that the current website session or Pro access is valid. appliedThemePublicId records the last visibly verified operation; it does not prove that a renderer created after a full quit is still themed.

Restart states also have distinct meanings:

State	Meaning
`pending_confirmation`	The user has not approved the controlled reload.
`restart_approved`	Approval exists, but the final theme has not been verified.
`running`	The one-time Helper is still working.
`completed`	The restart transaction reached terminal success. Check the matching ID or `restartKind`.
`failed`	Report the current stable `restartErrorCode` and take its documented action.

There is no runtimeStatus or session keeper in the current on-demand design.

Plugin installation

Confirm that the installed list contains exactly one codex-skin@codex-skin entry with installed: true and enabled: true:

codex plugin list --json

Then completely quit Codex, reopen it, start a new task, and run:

$codex-skin-version

The current Production Paid Alpha reports Plugin 0.1.0-paid-alpha, Helper .17, Bootstrap .16, and https://codexskin.ai. It is a GitHub prerelease, not stable/latest.

If Marketplace add, upgrade, or Plugin add fails, keep a working Plugin installed. Save the failing command and its original error. Do not edit Codex configuration or delete Marketplace and Plugin cache directories. The Plugin guide documents the one reversible Marketplace refresh.

Apply or Switch is still running

An ordinary Apply or Switch usually takes 20–60 seconds. During that period, do not click, type, navigate, or close the current Codex window. You may use an authorization or Pricing page that the operation opened in the browser.

Do not submit a second request because the first one looks quiet. If you accidentally interact with the Codex window, leave the original command active. A long operation should receive at most one reminder until its state changes.

If a controlled reload has already been approved or is running, a competing request can return CS-FLOW-RESTART-002. Wait for the current transaction to finish, then read Status.

Authorization and access errors

CS-FLOW-AUTH-001 means the protected device authorization did not complete. Finish or retry the approval on the official Codex Skin page. The original request keeps its six-digit ID; do not substitute another ID to fix authorization.

CS-FLOW-ACCESS-001 means Pro access did not become ready within the bounded wait. Finish the purchase, or check the current account and access state. Do not treat a callback page, editable local file, or cached package as proof of Pro access.

Free and Pro package downloads both require an authorized Plugin device. Pro themes add the access check. Pro access explains expiry, refund, and reapply rules, while Pricing remains the price source.

Restart states

CS-FLOW-RESTART-001 with action confirm_restart is a request for explicit consent, not a failure after mutation. Answer yes or no. Do not run the continuation before yes, and do not launch it twice.

After approval, the one-time Helper owns the exact close, reopen, Apply or Restore, visible verification, and cleanup. restartAccepted: true, restart_approved, and running are not success.

Once Codex returns, read Status. If it remains running, wait briefly and check again for no longer than 60 seconds. Apply or Switch needs completed plus the requested public ID and version. Restore needs restartKind: restore plus restartStatus: completed.

Theme or package errors

Check that the request contains one published six-digit ID from the theme gallery. Do not use a theme name as a substitute, invent an ID, or supply a local package or download URL.

Package download and verification happen before commit. A wrong signature, hash, schema, path, content type, size, or platform stops the package rather than partially applying it. Keep the stable code returned by the current operation and report it without a private URL, storage key, or local package path.

If the catalog no longer exposes the ID, return to the gallery and choose a published theme. If the ID is published but the package still fails, stop repeated attempts and report the current code.

Verification and rollback

CS-FLOW-VERIFY-001 means the one-time Helper could not prove that the requested theme reached the final renderer state. It does not mean that a downloaded or partly visible theme should be accepted as success.

Read current Status. If it does not report a rollback problem, retry the requested Apply once after the current operation has ended. Do not infer the current state from a code quoted in an earlier conversation.

CS-FLOW-ROLLBACK-001 means the current operation could not confirm safe rollback. Use the authoritative Restore guide before another Apply or Switch. Do not manually remove markers, state, or recovery files.

After a Codex update

A full quit, computer restart, renderer reload, or Codex update can end the visible guarantee without meaning that the previous package was corrupt. Open Codex and request the theme again.

Before a new Apply, the Helper checks official identity, loopback control, required renderer structures, capabilities, and final markers. If an update makes the fixed contract missing or ambiguous, the new operation stops safely. There is no Guardian or background auto-repair service that guesses at a changed interface.

Keep the recovery point. You can use Restore even when a new Apply cannot prove compatibility. Safety and compatibility explains why a compatibility stop differs from an ordinary Codex failure.

Restore problems

Use the ordinary Plugin request first:

Codex Skin, restore the official Codex appearance.

When the Plugin path is unavailable, use the fixed offline launcher documented for macOS and Windows. Do not replace it with an unknown Helper.

If Restore asks for one controlled reload, give an explicit yes or no and launch it only once. If Restore or its continuation returns a stable failure code, report the code and stop. Do not delete state, recovery files, the offline launcher, or Plugin caches.

These commands are intended for an installation or Marketplace report:

codex --version
codex plugin marketplace list
codex plugin list --json

Include the failing command and its original error. Remove or avoid any device ID that is not needed for the report.

Do not share tokens, cookies, account or payment data, prompts, conversations, source code, project files, screenshots, absolute local paths, operation journals, or recovery contents. A reproducible public Plugin bug without private information can go to the public GitHub repository. Use Contact for private account or order help.

Error-to-action reference

Current code or state	Next action
`CS-FLOW-AUTH-001`	Finish or retry device authorization.
`CS-FLOW-ACCESS-001`	Finish purchase or check current Pro access. Do not duplicate the theme request.
`CS-FLOW-RESTART-001`	Answer the one explicit restart question; continue only after yes.
`CS-FLOW-RESTART-002`	Wait for the approved or running transaction to finish.
`CS-FLOW-VERIFY-001`	Check Status; retry only after the current operation ends and no rollback problem remains.
`CS-FLOW-ROLLBACK-001`	Use Restore before another Apply or Switch.
Restore failure	Report the stable current code and stop without deleting recovery files.