Skip to content

Troubleshooting

This guide covers common Starship issues and their solutions.

Installation Issues

Command Not Found

Symptom: starship: command not found

Solutions:

  1. Verify installation: 

    which starship
ls /usr/local/bin/starship

  2. Check PATH: 

    echo $PATH

  3. Reinstall: 

    curl -sS https://starship.rs/install.sh | sh

  4. Add to PATH manually: 

    export PATH="/usr/local/bin:$PATH"

Permission Denied

Symptom: Permission errors during installation

Solution:

# Use sudo with install script
curl -sS https://starship.rs/install.sh | sh -s -- --yes

# Or install to user directory
curl -sS https://starship.rs/install.sh | sh -s -- --bin-dir ~/.local/bin

Add ~/.local/bin to PATH:

export PATH="$HOME/.local/bin:$PATH"

Configuration Issues

Config File Not Loading

Symptom: Changes to starship.toml have no effect

Diagnosis:

  1. Check config location: 

    echo $STARSHIP_CONFIG
starship config

  2. Verify file exists: 

    ls -la ~/.config/starship.toml

  3. Check for syntax errors: 

    starship print-config

Solutions:

  1. Ensure correct path: 

    # Default location
mkdir -p ~/.config
touch ~/.config/starship.toml

  2. Set explicit config path: 

    export STARSHIP_CONFIG=~/.config/starship.toml

  3. Restart shell or source config: 

    source ~/.bashrc  # or ~/.zshrc

TOML Syntax Errors

Symptom: Starship shows errors or uses defaults

Diagnosis:

starship print-config 2>&1 | head -20

Common syntax issues:

# Wrong: Missing quotes on strings with spaces
style = bold green

# Correct
style = "bold green"

# Wrong: Using = inside section header
[git_branch = something]

# Correct
[git_branch]
something = value

# Wrong: Unclosed brackets
format = "[$branch($style)"

# Correct
format = "[$branch]($style)"

Module Not Showing

Symptom: A module doesn't appear when expected

Diagnosis:

starship explain

Common causes:

  1. Module disabled: 

    [module_name]
disabled = false  # Explicitly enable

  2. Detection not triggered: 

    # Check if files exist that trigger detection
ls package.json  # For nodejs
ls Cargo.toml    # For rust

  3. Not in format string: 

    format = """
$directory\
$git_branch\
$nodejs\  # Make sure module is listed
$character"""

  4. Conditional not met: 

    [hostname]
ssh_only = true  # Only shows via SSH

[time]
disabled = true  # Disabled by default

Display Issues

Symbols Not Rendering

Symptom: Boxes, question marks, or wrong characters instead of symbols

Cause: Missing Nerd Font

Solutions:

  1. Install a Nerd Font: 

    # macOS
brew tap homebrew/cask-fonts
brew install --cask font-fira-code-nerd-font

  2. Configure terminal to use the font:

  3. iTerm2: Preferences > Profiles > Text > Font
  4. Terminal.app: Preferences > Profiles > Font

  5. VS Code: Settings > Terminal > Integrated: Font Family

  6. Use text-only symbols: 

    [git_branch]
symbol = "git:"

[nodejs]
symbol = "node:"

[python]
symbol = "py:"

Colors Not Showing

Symptom: Prompt appears in plain text without colors

Causes:

  1. Terminal doesn't support colors: 

    echo $TERM
# Should show something like xterm-256color

  2. True color not supported: 

    # Test true color support
printf "\x1b[38;2;255;100;0mTRUECOLOR\x1b[0m\n"

Solutions:

  1. Set TERM correctly: 

    export TERM=xterm-256color

  2. Use basic colors in config: 

    # Instead of hex colors
style = "bold blue"
# Not
style = "bold #61afef"

Prompt Appears on Wrong Line

Symptom: Text wrapping issues or cursor on wrong line

Cause: Hidden characters not properly escaped

Solution:

Check shell-specific escaping. The init script usually handles this, but manual configurations may need:

# Bash: \[ and \] around non-printing chars
# Zsh: %{ and %} around non-printing chars

Starship handles this automatically - ensure you're using the proper init:

eval "$(starship init bash)"  # or zsh, fish

Garbled Output in tmux

Symptom: Prompt looks wrong in tmux

Solutions:

  1. Set proper TERM in tmux: 

    # In .tmux.conf
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",xterm-256color:Tc"

  2. Reload tmux: 

    tmux source-file ~/.tmux.conf

Performance Issues

Slow Prompt

Symptom: Noticeable delay before prompt appears

Diagnosis:

starship timings

Solutions:

  1. Disable slow modules: 

    [git_status]
disabled = true

[package]
disabled = true

  2. Reduce git_status scope: 

    [git_status]
ignore_submodules = true

  3. Set command timeout: 

    command_timeout = 500

  4. Reduce detection: 

    [nodejs]
detect_extensions = []
detect_files = ["package.json"]
detect_folders = []

Very Slow in Large Repos

Symptom: Multi-second delay in large Git repositories

Solutions:

  1. Disable git_status: 

    [git_status]
disabled = true

  2. Configure Git for large repos: 

    git config core.commitGraph true
git config gc.writeCommitGraph true
git commit-graph write --reachable

  3. Use sparse checkout for very large repos

Shell-Specific Issues

Bash Completion Broken

Symptom: Tab completion stops working after enabling Starship

Solution:

Ensure Starship init is at the END of .bashrc, after completion setup:

# Load completions first
source /etc/bash_completion

# Starship LAST
eval "$(starship init bash)"

Zsh Slow Startup

Symptom: Shell takes long to start

Diagnosis:

time zsh -i -c exit

Solutions:

  1. Use async loading (with zinit or similar)

  2. Profile startup: 

    zsh -xv 2>&1 | head -100

  3. Compile Starship init: 

    # In .zshrc before eval
starship init zsh > ~/.config/starship/init.zsh
source ~/.config/starship/init.zsh

Fish Issues

Symptom: Starship not loading in Fish

Solution:

Ensure init is in the right file:

# ~/.config/fish/config.fish
starship init fish | source

Git Issues

Git Branch Not Showing

Symptom: No branch displayed in Git repo

Diagnosis:

git branch
git rev-parse --git-dir

Solutions:

  1. Verify you're in a Git repo

  2. Check if git_branch is disabled: 

    [git_branch]
disabled = false

  3. Ensure Git is installed and in PATH

Wrong Git Status

Symptom: Status symbols incorrect or missing

Solutions:

  1. Check actual Git status: 

    git status

  2. Verify format includes all_status: 

    [git_status]
format = '[$all_status$ahead_behind]($style) '

  3. Check individual status symbols: 

    [git_status]
untracked = "?"
modified = "!"
staged = "+"
# etc.

Custom Module Issues

Custom Command Not Working

Symptom: Custom module doesn't appear or shows wrong output

Diagnosis:

  1. Test command manually: 

    # Run the exact command from your config
echo $(your-command)

  2. Check when condition: 

    # Test the when condition
test -f package.json && echo "would show"

Solutions:

  1. Ensure command is available: 

    [custom.mymodule]
command = "/full/path/to/command"

  2. Fix when condition: 

    [custom.mymodule]
# Use proper shell syntax
when = "command -v mycommand >/dev/null"

  3. Specify shell: 

    [custom.mymodule]
shell = ["bash", "-c"]

Getting Help

Generate Bug Report

starship bug-report

This generates diagnostic information including:

  • Starship version
  • Shell information
  • Configuration
  • Environment variables

Check Version

starship --version

Official Resources

Debugging Steps

  1. Check explain output: 

    starship explain

  2. View timings: 

    starship timings

  3. Print config: 

    starship print-config

  4. Enable logging: 

    STARSHIP_LOG=trace starship prompt

  5. Test minimal config: 

    # Backup current config
mv ~/.config/starship.toml ~/.config/starship.toml.bak

# Test with empty config
touch ~/.config/starship.toml

# Restart shell and check if issue persists