---
title: Troubleshooting
description: Resolve common Zsh Lint installation, input, parser, and exit-code problems.
canonical_url: https://wiki.zshell.dev/community/zsh_lint/zsh-lint-troubleshooting
markdown_url: https://wiki.zshell.dev/community/zsh_lint/zsh-lint-troubleshooting/index.md
locale: en
source_path: community/04_zsh_lint/06_troubleshooting.mdx
---

<!-- Generated from the canonical Z-Shell Wiki build. The linked human-facing page remains the editorial source of truth. -->

# Troubleshooting

<a id="zsh-lint-command-not-found"></a>

## `zsh-lint: command not found`

Go normally installs binaries under `$(go env GOPATH)/bin`. Add that directory to `PATH`, or invoke the binary directly:

```sh
"$(go env GOPATH)/bin/zsh-lint" path/to/script.zsh
```

<a id="passing-a-directory-fails"></a>

## Passing a directory fails

The published CLI opens each argument as one file. It does not recurse through directories. Build an explicit file list as described in [Choosing files](https://wiki.zshell.dev/community/zsh_lint/zsh-lint-choosing-files/index.md).

<a id="a-bash-or-sh-file-reports-strange-parse-errors"></a>

## A Bash or `sh` file reports strange parse errors

Zsh Lint does not classify dialects from the shebang or extension. Every path you pass is parsed as Zsh. Remove non-Zsh files from the input list.

<a id="valid-zsh-reports-a-parser-error"></a>

## Valid Zsh reports a parser error

First check the same file with the supported native Zsh version:

```sh
zsh -f -n -- path/to/script.zsh
```

If native Zsh accepts it, collect a minimal example and report a parser gap in [z-shell/zsh-lint](https://github.com/z-shell/zsh-lint/issues). Do not rewrite valid native Zsh only to satisfy a supplemental parser.

<a id="--config-is-rejected"></a>

## `--config` is rejected

The option needs v1.2.0 or newer, and automatic discovery plus `--no-config` need v1.3.0; an older pinned binary prints the usage line instead. Upgrade the pin, then see [Project configuration](https://wiki.zshell.dev/community/zsh_lint/zsh-lint-project-configuration/index.md).

<a id="exit-status-1-with-no-obvious-error"></a>

## Exit status 1 with no obvious error

Warnings also return status 1. Read the human diagnostics or save JSON and inspect the summary:

```sh
zsh-lint --format=json path/to/script.zsh | jq '.summary'
```

Because the linter itself exits 1 for findings, append `|| status=$?` only when you are deliberately inspecting output. Do not hide the failure in CI.

<a id="an-intentional-pattern-keeps-failing"></a>

## An intentional pattern keeps failing

Read the rule, verify that the code is intentional, then add a line-scoped suppression with the exact rule ID and a reason. See [Rules and suppressions](https://wiki.zshell.dev/community/zsh_lint/zsh-lint-rules-and-suppressions/index.md).