Debugging

Things to reach for when "but it works on my machine" happens.

STARSHIP_LOG

The first lever to pull:

STARSHIP_LOG=trace starship prompt

Level	What you get
error (default)	Only errors
warn	+ warnings (e.g. failed config parse, format string error)
info	+ lifecycle events
debug	+ per-module decisions
trace	+ every command spawn, file read, env-var lookup

Logs go to ${STARSHIP_CACHE:-$HOME/.cache}/starship/session_<id>.log for in-shell runs (the shell's pid + invocation count is the id) and to stderr for one-off CLI runs. Set STARSHIP_LOG in your shell's rc to debug the actual prompt.

starship explain

$ starship explain

 Here's a breakdown of your prompt:
 "with 🦀 v1.85.0 (1ms)"  -  The currently installed version of Rust
 "[]"                     -  ...

Tells you which modules ran, how long each took, and what they emitted. Backed by src/print.rs::explain.

starship timings

Same as explain but ordered by descending compute time, and only shows modules taking ≥1ms. Use this to find the culprit when your prompt feels sluggish.

starship module <name>

Renders just one module. Useful when you know which module is misbehaving:

starship module git_status

starship print-config

# What does my effective config look like?
starship print-config

# What are the defaults?
starship print-config --default

# Just one section
starship print-config rust

If you suspect your starship.toml isn't being read at all:

echo $STARSHIP_CONFIG  # Did you set this?
ls ~/.config/starship.toml

Reproducing real-shell behavior in a sandbox

To bisect "this only happens in zsh," start a clean zsh:

zsh --no-rcs -c '
  export STARSHIP_LOG=trace
  eval "$(/path/to/starship init zsh)"
  cd /tmp && touch x.rs && \
  echo "PROMPT TEST"
'

--no-rcs skips your dotfiles, so any oddity is from starship + the shell, not from interactions with your normal setup.

Debugging a flaky test

Tests run in parallel by default. To isolate flakiness:

cargo test --all-features test_name -- --nocapture --test-threads=1

--nocapture shows the println!/log! output during the test; --test-threads=1 runs serially to rule out tempdir collisions.

Gix repo issues

Almost every git module bug comes down to gix discovering or opening the repo. To inspect:

RUST_LOG=trace cargo run -- prompt 2>&1 | grep -i gix

Context::get_repo logs at debug when it fails to discover a repo and at trace when it succeeds.

cargo expand for macros

The clap::Parser derive on Cli and the serde::Deserialize derives on every config struct hide a lot. To see what they generate:

cargo install cargo-expand
cargo expand --bin starship 2>&1 | less

Rare: panic backtraces

Modules should never panic, but if one does:

RUST_BACKTRACE=full starship prompt

The [profile.release] section in Cargo.toml strips symbols, so debug builds (cargo build) give cleaner backtraces.

Common gotchas

• Module doesn't appear — Is disabled set? Is the module listed in your format string (or covered by $all)? Is the project detected (check detect_files/detect_extensions/detect_folders)?
• Wrong color — Is your terminal a Nerd Font terminal? Are you in a TERM=dumb setup? Is your config palette wrong?
• Slow prompt — Run starship timings. The usual suspects are git_status and git_metrics on big repos. Increase command_timeout or disable the module.
• Random ANSI escape garbage — Some shells need to know which characters in the prompt are non-printing. The wrap_colorseq_for_shell step in src/utils/mod.rs handles this; if your shell isn't recognized, set STARSHIP_SHELL correctly.

Issues to file

Use starship bug-report to pre-fill the GitHub issue body with your environment. Review the body before submitting (it includes your starship.toml verbatim).