Troubleshooting

This page collects common problems with CoffeeLint, organized by symptom, with their causes and fixes.

My Configuration Is Not Being Applied

Symptoms: rules you changed still behave as the defaults; different machines report different results.

Check, in this order:

1. Are you passing --noconfig? It ignores all configuration, including -f.
2. Is COFFEELINT_CONFIG set? If it points to an existing file, that file wins over every project file. Run echo $COFFEELINT_CONFIG (or echo %COFFEELINT_CONFIG% on Windows).
3. Is there a closer package.json with coffeelintConfig? It takes precedence over any coffeelint.json. Only the nearest package.json is checked.
4. Is there a closer coffeelint.json? Discovery starts from each linted file's directory and stops at the first match, so a stray config in a subfolder overrides the root one for files below it.
5. Is the file valid JSON? A malformed discovered configuration prints Could not load JSON file '...' to standard error and is then ignored, so the defaults apply. Look for that message at the top of the output.
6. Is extends involved? It is ignored for files loaded with -f.

Run coffeelint --trimconfig from the project directory to print the configuration CoffeeLint actually resolves there. See Configuration for the full discovery order.

A Rule Name in My Config Has No Effect

Unknown rule names are silently ignored, so a typo (max_line_lenght) just does nothing. Run coffeelint --trimconfig: unrecognized rules are missing from its output. Check the exact names in the Rules Overview.

colon_assignment_spacing Reports Every Line

You probably set only one side of spacing, for example { "right": 1 }. The spacing object replaces the default as a whole, so the other side becomes undefined and never matches. Always set both left and right.

braces_spacing Complains About {}

empty_object_spaces defaults to 0 and is always present after the merge with the defaults, even when you set spaces: 1. Set empty_object_spaces explicitly if you want { }.

Directories Are Linted but Some Files Are Missing

• Only *.coffee files are collected from directories. Add other extensions with --ext, for example --ext litcoffee.
• node_modules is always skipped.
• Check .coffeelintignore. It is read from the current working directory, and its patterns match normalized paths such as src/app.coffee. Running CoffeeLint from another directory changes which patterns apply.

The summary line shows how many files were linted (in 0 files is a strong hint that nothing matched).

The Build Passes Even Though Problems Are Reported

Only error-level findings set the exit code to 1. Warnings are reported but never fail the run. Promote the rules that must block a build to "level": "error".

Only a Syntax Error Is Reported

When a file has a CoffeeScript syntax error, CoffeeLint reports coffeescript_error and skips the token and line passes, and inline directives are not applied. Fix the syntax error and lint again to see the rest.

If code that works with your build fails to parse, remember that CoffeeLint 2.1.0 uses the CoffeeScript 2 compiler. Code written for CoffeeScript 1 may need updating.

unknown level ... for rule ...

A rule's level is something other than ignore, warn, or error (the check is case-sensitive). Fix the value in your configuration.

unknown line ending type

line_endings.value must be unix or windows.

Custom Rules Fail to Load

Message	Cause and fix
Error loading <module> followed by a stack trace	The module could not be required. Install it in the project (npm install --save-dev <module>) and check the name in module or --rules.
Invalid rule: <name> Mismatched rule name: <key>	The configuration key differs from the name declared in the rule. Use the rule's exact name as the key.
Invalid rule: ... Rules must implement lintToken, lintLine, or lintAST	The module does not export a valid rule class. If it is written in CoffeeScript, make sure it is compiled or that its entry point registers the compiler.
Invalid rule: ... 'tokens' is required for 'lintToken'	A token rule is missing its tokens array.

See Writing Custom Rules.

Line Numbers Are Wrong

If you use transforms, a transform probably adds or removes lines. Look for the transform_messes_up_line_numbers warning. Even without that warning, a transform that adds and removes the same number of lines shifts the lines in between.

A Transform Seems to Have No Effect

Transforms that fail to load or throw are skipped silently. Check that the module resolves from the linted file's directory (for discovered configuration) and that node -p "require('your-transform')" works.

CSV Output Is Misaligned

The CSV reporter does not quote fields, so commas inside messages or paths shift the columns. Use --reporter raw, jslint, or checkstyle for robust parsing. See Reporters.

Results Seem Stale with --cache

Cache entries are keyed by the CoffeeScript and CoffeeLint versions, the configuration, and the file's content, so normal edits invalidate them. If you change something the key does not cover, such as the code of a custom rule or transform, delete the coffeelint folder in your system's temporary directory.

The Global Command Runs a Different Version

The globally installed coffeelint executable deliberately runs the project's own coffeelint dependency when one exists. Run coffeelint --version inside the project to see which version is used. See Installation.

--literate Has No Effect on Files

--literate only applies to --stdin. For files, literate mode is chosen by extension (.litcoffee, .coffee.md).