Debugging license problems

Tidelift's license scanning compares the output of your package manager's license metadata and your source repository's license metadata. If they don't match, or are missing, we report a problem and ask you to fix it. We want accurate machine-readable license information so subscribers can verify and report their license compliance.

Below are some common causes of license problems, steps to debug, and suggested solutions.Remember: you can always contact us at lift@tidelift.com—we're happy to help walk you through debugging and deciding on next steps.

GitHub reports no license data

GitHub can report no license data in two cases: you provide no license data, or you provide too much license data. (You can check what GitHub reports by looking at the license information shown in the GitHub web view (upper right hand corner), or if you have a GitHub API key, checking the license API.)

Too much/little license information

Unfortunately, GitHub's API tells us "no license detected" both when there is too little, and too much, license information. So we can't currently automatically distinguish between the two cases. (We'll improve that in the future.) Here's some more information on the potential root causes of the problem.

No license data in the source repository

GitHub's license scanner looks at a variety of files, primarily any license in the root directory whose filename includesLICENSE. (It does not, by default, checkREADME.) It then compares the contents of those files to the full text of known licenses. If you don't have license information in a LICENSE file, or the license information is simplistic ("This project is under the BSD license" rather than full license text), GitHub will report that it found no licensing information.

Complex license data in the source repository

GitHub's license scanner, licensee, deliberately fails whenever it sees complex license information, like a SECONDARY-LICENSES or LICENSE-DEPENDENCIES file, or simply a LICENSE file with more than one license. So if your license documentation attempts to diligently and carefully explain a complex situation, like vendored dependencies, GitHub will report that it found no licensing information.

Debugging GitHub issues

  1. If you don't have a LICENSE file (or similar), that's probably the problem. See No license information below for suggested next steps.
  2. If more than one filename containsLICENSE, GitHub is likely confused by this. See Complex license information below for suggested next steps.
  3. If you have only one LICENSE file, you can compare it to GitHub's internal representation of the standard license by installing licensee and running licensee diff. This may point out problems like formatting that are confusing GitHub's scanner even on simple files.

Fixing GitHub issues

NO LICENSE INFORMATION

If the project genuinely has no license information, follow GitHub's directions to license the project.

COMPLEX LICENSE INFORMATION

We can't fix GitHub's license scanning in the case where there is more than one license file with conflicting information. Their suggested solution is to move complex information to a file whose name does not contain "LICENSE". We don't recommend or require this approach, because we think it obscures the genuine complexity that your users are required to deal with.

Instead, in this situation we will typically ask you to ensure that your package manager metadata accurately reflects the complex situation. For example, if your source code is under the bsd-3-clause license, and your LICENSE-DEPENDENCIES file mentions a vendored dependency under apache-2.0, your package manager's metadata should mention both bsd-3-clause and apache-2.0. (Dependencies that are managed through the package manager don't need to be tracked this way - they should surface their licensing to your users through their own license metadata.)

How you do this may depend on which package manager you're using. For example:

  • in npm's package.json, use an SPDX license string: bsd-3-clause AND apache-2.0(docs)
  • in RubyGems' gemspec or Rakefile, licenses = [BSD-3-Clause, Apache-2.0](docs)

For other examples, see our licensing docs.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us