Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

`codex doctor` fails the terminal check when any TERMINFO_DIRS entry does not exist

Open Beginner friendly
  • Is something wrong?
#48,707 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
85/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
rust
Domain
cli, testing

Research direction

Start in codex-rs/cli/src/doctor.rs at push_terminfo_details and terminal_path_readiness, then review the snapshot test terminal_check_prioritizes_unreadable_terminfo_over_warnings. Reproduce the mixed TERMINFO_DIRS cases from the issue and add coverage for them; done means missing search-path entries are informational while genuinely unreadable or unresolved terminal data still reports a problem.

Written by the indexing model from the issue text.

Description

bug CLI
What version of Codex CLI is running?

0.157.1 (codex-package-x86_64-unknown-linux-musl); the same code is on main.

What subscription do you have?

Plus

Which model were you using?

N/A (codex doctor only)

What platform is your computer?

Linux 7.2.7 x86_64 (NixOS)

What terminal emulator and version are you using (if applicable)?

Any. The check depends only on the environment.

Codex doctor report
✗ terminal     TERMINFO unreadable - terminal capabilities are unknown
    TERM                 xterm-256color
    TERMINFO_DIRS entry  /home/user/.local/share/flatpak/exports/share/terminfo (missing)
    TERMINFO_DIRS entry  /var/lib/flatpak/exports/share/terminfo (missing)
    TERMINFO_DIRS entry  /home/user/.nix-profile/share/terminfo (missing)
    TERMINFO_DIRS entry  /nix/profile/share/terminfo (missing)
    TERMINFO_DIRS entry  /home/user/.local/state/nix/profile/share/terminfo (missing)
    TERMINFO_DIRS entry  /etc/profiles/per-user/user/share/terminfo (dir)
    TERMINFO_DIRS entry  /nix/var/nix/profiles/default/share/terminfo (missing)
    TERMINFO_DIRS entry  /run/current-system/sw/share/terminfo (dir)
What issue are you seeing?

The terminal check reports Fail with "TERMINFO unreadable - terminal capabilities are unknown" whenever any entry in TERMINFO_DIRS does not exist, even though other entries are readable and contain the entry for $TERM.

TERMINFO_DIRS is a search path. ncurses and other terminfo readers skip missing entries. Distributions often set it to a list of candidate profile directories where only some exist. NixOS does this by default: it lists every possible Nix and flatpak profile. So on a stock NixOS install codex doctor always fails this check, even though terminal capabilities resolve fine.

The cause is in push_terminfo_details (codex-rs/cli/src/doctor.rs). Each TERMINFO_DIRS entry goes through terminal_path_readiness, which returns warning = true for NotFound. The results are OR-ed into has_warning, and that raises the CheckStatus::Fail issue.

What steps can reproduce the bug?
# passes
TERM=xterm-256color TERMINFO_DIRS=/usr/share/terminfo codex doctor

# fails: a missing entry first or last is enough
TERM=xterm-256color TERMINFO_DIRS=/nonexistent:/usr/share/terminfo codex doctor
TERM=xterm-256color TERMINFO_DIRS=/usr/share/terminfo:/nonexistent codex doctor

(Replace /usr/share/terminfo with any existing terminfo directory.)

What is the expected behavior?

Missing TERMINFO_DIRS entries should be listed in the details as informational, not treated as a failure. A reasonable rule would be to report a problem only when:

  • $TERMINFO, which names one explicit directory, is set but unreadable; or
  • no entry in TERMINFO_DIRS exists or is readable; or, stricter,
  • no terminfo entry for $TERM can be found on the effective search path.

Unreadable entries that exist, such as permission errors, could still be flagged as a warning.

Additional information

The existing snapshot test terminal_check_prioritizes_unreadable_terminfo_over_warnings covers an unreadable TERMINFO. It doesn't cover a mixed TERMINFO_DIRS list, which is where this regression hides.

I used an AI assistant (Claude Code) to help investigate and draft this report. I reproduced and verified the behavior myself.

Dominant language
Rust
Stars
127k
Forks
19.9k
Avg merge
1m
Merged PRs (30d)
996

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openai/codex

All issues in openai/codex

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.