Troubleshooting

Troubleshooting

conversation.codex_assist does not appear

Try this first:

1. Restart Home Assistant after installing or updating.
2. Confirm Codex Assist appears under Settings → Devices & services.
3. Reload the config entry if the integration exists but the conversation entity is missing.
4. Check Home Assistant logs for codex_assist setup errors.

Codex Assist appears but is not used by Assist

Confirm your Assist pipeline uses Codex Assist as the conversation agent. Installing the integration is not always enough; the pipeline must be configured to use it.

The agent answers but cannot control devices

Usually this is an Assist exposure issue.

Check:

• the target entity is exposed to Assist
• the entity is available in Home Assistant
• the device can be controlled manually from Home Assistant
• the request uses a clear name or alias

Start with one exposed light before testing more complicated devices.

Auth stops working or model calls return 401

Codex Assist refreshes tokens before model calls. Upstream auth can still be invalidated before the token's local expiry time, so current releases also retry once after a server token_invalidated response. If refresh still fails, Home Assistant should raise a Repair issue and offer reauthentication instead of returning raw auth JSON in the Assist chat.

Try:

1. Open Home Assistant Repairs or the Codex Assist integration page.
2. Complete the reauth flow if offered.
3. Retry with a harmless exposed entity, such as asking whether a light is on and then turning it off.
4. Restart Home Assistant if the entity remains stuck after reauth.
5. Check logs for codex_assist errors.

HACS installed an older version

HACS may cache available releases. Refresh HACS, confirm the release version, install the update, and restart Home Assistant.

Where to report issues

Open a GitHub issue for normal bugs. Do not post tokens, cookies, private logs, or Home Assistant secrets publicly. For sensitive reports, follow the repository Security Policy.