Troubleshooting

This guide covers common issues and their solutions when using Lintro.

Common Issues

“Command not found: lintro”

Cause: Lintro is not installed or not in your PATH.

Solution: Ensure Lintro is installed correctly:

pip install lintro
# or with pipx (recommended for CLI tools)
pipx install lintro
# or for development
pip install -e .

If using pipx, ensure ~/.local/bin is in your PATH.

“Tool not found” errors

Cause: The underlying tool (e.g., ruff, prettier) is not installed on your system.

Solution: Install the required tools or use Docker:

# Install tools individually
pip install ruff pydoclint
npm install -g prettier
pip install yamllint

# Or use Docker (recommended - includes all tools)
docker run --rm -v $(pwd):/code ghcr.io/lgtm-hq/py-lintro:latest check

See Getting Started for complete installation instructions.

Permission errors on Windows

Cause: Windows may require elevated privileges for certain operations.

Solution: Run as administrator or use WSL:

# Use WSL for better compatibility
wsl
pip install lintro

WSL provides a Linux environment with better tool compatibility.

Docker permission issues

Cause: Permission errors when running lintro in Docker.

Solution: Lintro’s Docker image automatically detects the volume owner’s UID and runs as that user. No extra flags are needed:

docker run --rm -v "$(pwd):/code" ghcr.io/lgtm-hq/py-lintro:latest check

If you’re in a restricted environment (e.g., Kubernetes with runAsNonRoot), pass your user explicitly:

docker run --rm -v "$(pwd):/code" --user "$(id -u):$(id -g)" ghcr.io/lgtm-hq/py-lintro:latest check

If you get “permission denied” errors accessing the Docker socket (/var/run/docker.sock), add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in for the group change to take effect

See Docker Volume Permissions for details.

Node.js dependency errors (TS2307, TS2688, TS7016)

Cause: TypeScript tools report “Cannot find module” errors when node_modules is missing.

Solution: Install dependencies or use auto-install:

# Option 1: Install dependencies manually
bun install
# or
npm install

# Option 2: Use --auto-install flag
lintro check src/ --tools tsc --auto-install

# Option 3: Enable auto-install in configuration
# .lintro-config.yaml
execution:
  auto_install_deps: true

Lintro categorizes tsc errors to help you distinguish between:

Dependency errors: Missing modules due to uninstalled packages
Type errors: Actual TypeScript issues in your code

When dependency errors are detected, Lintro shows the missing module names and suggests running bun install or using --auto-install.

Note: Docker automatically installs Node.js dependencies when the container starts, so this issue typically only affects local usage.

Slow performance

Cause: Scanning large directories or running all tools unnecessarily.

Solution: Use exclude patterns and specific tools:

# Exclude large directories
lintro check --exclude "node_modules,venv,.git,dist,build"

# Run specific tools only
lintro check --tools ruff,prettier

Every tool passes with 0 issues

Cause: Nothing was actually scanned. The summary table marks such rows with a no files matched note — a run where every tool carries that note inspected no files at all.

Solution: Check your exclusions. Exclude patterns from .lintro-ignore and the built-in defaults are gitignore-style and are interpreted relative to the project root (the nearest directory containing .lintro-ignore, .lintro-config.yaml, pyproject.toml, package.json or .git). Directories above that root never exclude your files, so a checkout living under a path such as ~/build/my-project is scanned normally. Inside the project, verify the paths you passed are not matched by a pattern:

lintro check --verbose

A tool that could not run at all is reported separately as a ⏭️ SKIP row with the reason, never as a pass.

Configuration not being applied

Cause: Lintro may not be finding your configuration file.

Solution: Check configuration resolution order:

CLI arguments (highest priority)
.lintro-config.yaml in current directory
pyproject.toml [tool.lintro] section
Default settings

Verify your config is being loaded:

lintro check --verbose

See Configuration for detailed configuration options.

Output format issues

Cause: Terminal doesn’t support colors or encoding issues.

Solution: Adjust output settings:

# Disable colors
lintro check --no-color

# Use simple output format
lintro check --output-format simple

# Force UTF-8 encoding
export PYTHONIOENCODING=utf-8
lintro check

Tool version conflicts

Cause: Different versions of tools may produce different results.

Solution: Pin tool versions in your project:

# Check installed versions
lintro list-tools --verbose

# Use Docker for consistent versions
docker run --rm -v $(pwd):/code ghcr.io/lgtm-hq/py-lintro:latest check

Reading `lintro install` results

Every planned action is attempted, and each one is reported on its own numbered line — an early failure or timeout never stops the tools after it from being installed:

  [1/3] FAIL  golangci_lint (2.1s)
  [2/3] TIMEOUT  clippy (300.0s)
  [3/3] OK  ruff (4.5s)

Label	Meaning
`OK`	Discoverable; meets `min_version` (unparseable output still OK).
`PATH`	Command succeeded, but the tool is still not discoverable.
`STALE`	Discoverable after the command, but still below `min_version`.
`FAIL`	Command ran and failed; re-running it unchanged will not help.
`TIMEOUT`	Command exceeded the 5-minute install timeout; retry is valid.
`MANUAL`	No runnable command exists here; install the tool by hand.

Wrapper-probed tools (bash/sh/cargo version commands, or an argv[0] containing /) still skip the PATH discoverability check, because those probes cannot tell whether the tool itself is discoverable. They still report STALE when a parsed version is below min_version. A project-local npm add whose binary lands in <project>/node_modules/.bin is discoverable: planning, post-install verification, and lintro doctor share the same local-first probe, so a successful npm install -D is not reported as PATH just because that directory is not on PATH. The bunx/npx registry fallback is not an install and is never treated as discoverable.

lintro install exits 1 when any planned action is not a full success, including PATH (NOT_DISCOVERABLE) and STALE (STILL_OUTDATED). A zero-exit install command is not enough.

A PATH result names the install destination directory and the PATH remedy. For a project-local npm add that directory is the detected project’s node_modules/.bin.

lintro doctor only suggests a quick fix for tools it can actually install in the detected environment; anything else is listed under “Needs manual action” with the reason. Failed remedies (FAIL, PATH, STALE, MANUAL) are recorded in a per-process known_invalid set: within one run the identical command is never re-suggested; a fresh run gets one fresh attempt. There is no state file.

Getting Help

If your issue isn’t covered here:

Documentation: Check the documentation directory for detailed guides
Bug Reports: Use the bug report template
Questions: Use the question template
Feature Requests: Use the feature request template

Reporting Bugs

When reporting bugs, please include:

Lintro version (lintro --version)
Python version (python --version)
Operating system
Complete error message
Minimal reproduction steps
Configuration file (if applicable)