> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting & FAQs

> Answers to common questions and troubleshooting guidance for SCANOSS tools, integrations, and APIs.

## SBOM Workbench

### What is the SCANOSS SBOM Workbench?

The SCANOSS [SBOM Workbench](https://github.com/scanoss/sbom-workbench) is a graphical user
interface tool for scanning and auditing source code, and for generating SBOMs.

### How do I configure API keys in SBOM Workbench?

1. Go to **File > Settings > API Connections**.
2. Add your API key and Knowledge Base URL.
3. Restart the application completely.

If the key does not appear:

* Ensure the key is valid and not expired.
* Confirm the URL format is correct (e.g. `https://api.scanoss.com`).

### Why can I not export or import projects in SBOM Workbench?

For export issues:

* Check write permissions.
* Ensure sufficient disk space.

For import issues:

* Verify the file is not corrupted (SBOM Workbench will report validation errors during import).
* Confirm version compatibility.

You may also export as CycloneDX or SPDX for interoperability.

### How can I integrate SBOM Workbench with CI/CD pipelines?

SBOM Workbench is a GUI tool and is not designed for direct CI/CD integration. For pipeline
use, consider:

* `scanoss-py`
* `scanoss.js`
* `gha-code-scan`
* Jenkins or Azure DevOps integrations

You may export a baseline SBOM from SBOM Workbench for use in pipelines.

### Why am I seeing an error with remote file access in SBOM Workbench?

Check internet connectivity, repository accessibility, and authentication credentials for
private repositories.

***

## SCANOSS.PY

### What is SCANOSS.PY?

The [SCANOSS Python package](https://github.com/scanoss/scanoss.py) is a client library for
interacting with SCANOSS APIs and the scanning engine.

### How do I install SCANOSS.PY?

```bash theme={null}
pip install scanoss
```

Development version:

```bash theme={null}
pip install git+https://github.com/scanoss/scanoss.py.git
```

### How do I scan a project with SCANOSS.PY?

```bash theme={null}
scanoss-py scan .
scanoss-py scan -o results.json /path/to/project
```

### How do I exclude files or directories from scanning?

Create a `.scanossignore` file using `.gitignore` syntax.

```
node_modules/
dist/
build/
*.min.js
```

### Why does a scan hang or take too long?

Possible causes include large codebases, network latency, or large dependency directories.
Use `.scanossignore` to exclude irrelevant paths, increase timeout settings, or split scans
into smaller modules.

### Why does a scan fail with no clear error message?

Common causes include:

* Not scanning from the project root.
* Network or firewall blocking API access.
* Version incompatibility.

Update to the latest release and verify network connectivity.

### Why are dependency files not detected during a scan?

Check that:

* Dependency files are located in the project root or standard directories.
* File names are exact (case-sensitive on Linux).
* The format is supported (npm, pip, Maven, Go modules, NuGet, etc.).

If using the CLI, pass the `--dependencies` flag explicitly:

```bash theme={null}
scanoss-py scan --dependencies -o scan-output.json .
```

If you receive a connectivity error, verify network access to the API.

***

## SCANOSS.JS

### What is SCANOSS.JS?

The [SCANOSS JavaScript/Node.js client library](https://github.com/scanoss/scanoss.js) for
interacting with SCANOSS APIs.

### How do I install SCANOSS.JS?

```bash theme={null}
npm install scanoss
```

Or globally:

```bash theme={null}
npm install -g scanoss
```

### How do I integrate SCANOSS.JS into a Node.js project?

```javascript theme={null}
const { Scanner } = require("scanoss");
const scanner = new Scanner();
scanner
  .scanDirectory("/path/to/project")
  .then((results) => console.log(results))
  .catch((error) => console.error(error));
```

***

## SCANOSS.JAVA

### What is SCANOSS.JAVA?

The [SCANOSS Java client library](https://github.com/scanoss/scanoss.java) for interacting
with SCANOSS APIs.

### How do I install SCANOSS.JAVA?

**Maven** (replace `1.x.x` with the desired release version):

```xml theme={null}
<dependency>
  <groupId>com.scanoss</groupId>
  <artifactId>scanoss-java</artifactId>
  <version>1.x.x</version>
</dependency>
```

**Gradle:**

```groovy theme={null}
implementation 'com.scanoss:scanoss-java:1.x.x'
```

***

## SCANOSS.CC (Code Compare)

### What is SCANOSS.CC?

The [SCANOSS Code Compare utility](https://github.com/scanoss/scanoss.cc) is a lightweight
command-line tool for comparing source code against the SCANOSS Knowledge Base.

### How do I install SCANOSS.CC?

```bash theme={null}
git clone https://github.com/scanoss/scanoss.cc.git
cd scanoss.cc
make
sudo make install
```

### Can SCANOSS Code Compare support multiple SPDX licences?

Yes. It reports all detected SPDX identifiers.

***

## CI/CD Integrations

### GitHub Actions

#### What is gha-code-scan?

The [gha-code-scan GitHub Action](https://github.com/scanoss/gha-code-scan) enables
automated SCANOSS scanning directly within GitHub Actions workflows.

#### How do I configure the SCANOSS GitHub Action?

Add the following to your workflow YAML:

```yaml theme={null}
uses: scanoss/gha-code-scan@v1
with:
  api-key: ${{ secrets.SCANOSS_API_KEY }}
```

### SonarQube

#### What is the SCANOSS integration with SonarQube?

The [SCANOSS SonarQube integration](https://github.com/scanoss/integration-sonarqube)
extends SonarQube analysis with SCANOSS licence and vulnerability data.

#### How do I integrate SonarQube or SonarCloud with SCANOSS?

Add the following to your Sonar configuration:

```properties theme={null}
sonar.scanoss.enabled=true
sonar.scanoss.apiUrl=https://api.scanoss.com
sonar.scanoss.apiKey=${SCANOSS_API_KEY}
```

Ensure SCANOSS scanning runs before SonarQube analysis.

#### Why am I receiving certificate errors during SonarQube scans?

Possible causes include incomplete certificate chains, corporate proxies, or incorrect HTTPS
configuration.

#### Why is scan latency high during SonarQube scans?

Optimise by excluding test and build directories, checking network bandwidth, or switching
to an on-premises deployment.

### Jenkins

#### What is the SCANOSS integration with Jenkins?

The [SCANOSS Jenkins integration](https://github.com/scanoss/integration-jenkins) is a
Jenkins plugin that enables SCANOSS scanning within CI pipelines.

#### How do I integrate Jenkins with SCANOSS?

Add SCANOSS steps in your Jenkins pipeline to run scans and archive results. Refer to the
repository for pipeline configuration examples.

### Azure DevOps

#### What is the SCANOSS integration with Azure DevOps?

The [SCANOSS Azure DevOps extension](https://github.com/scanoss/ado-code-scan) enables
SCANOSS scanning directly within Azure DevOps pipelines.

#### How do I install ado-code-scan?

Add the SCANOSS task to your Azure pipeline configuration. Refer to the repository for full
setup instructions.

***

## API & Authentication

### How do I obtain an API key?

API keys are provided under commercial licences. Contact [sales@scanoss.com](mailto:sales@scanoss.com)
or [support@scanoss.com](mailto:support@scanoss.com).

### Why is my API key not working or expired?

Check that:

* The key has not passed its expiry date.
* You are using the correct endpoint.
* There are no formatting errors (extra spaces, missing characters).
* Network connectivity to the API is available.

### Why are the Knowledge Base URL and API key not working together?

Ensure the URL format is correct (e.g. `https://api.scanoss.com`), the API key is correctly
formatted, and there are no network or firewall restrictions blocking access.

### Why is no response object returned from the API?

Possible causes include API downtime, network issues, rate limiting, or an incorrectly
formatted request payload.

### Where can I find the complete API documentation?

See the [SCANOSS PAPI repository](https://github.com/scanoss/papi) for the full API
documentation.

### Can SCANOSS retrieve licence, copyright, and source location using a software name and version?

Yes. You can use the Component Search service to search by software name and retrieve
licence and version-specific details using the component's PURL (Package URL). A PURL
uniquely identifies a specific package and version, allowing SCANOSS to return metadata
including licence information and source repository location.

Documentation:

* [SCANOSS Python client – general help](https://github.com/scanoss/scanoss.py/blob/main/CLIENT_HELP.md)
* [Component commands reference](https://github.com/scanoss/scanoss.py/blob/main/CLIENT_HELP.md#component-commands)

***

## Licences

### How are licences detected from open source software?

SCANOSS detects licences through:

* Licence file detection
* SPDX headers
* Copyright statements
* Package metadata
* Knowledge Base matching

### Why do multiple licences appear for the same component?

Open source components may be dual-licensed or contain files under different licences.
SCANOSS reports all detected licences. Licence compliance decisions should be made
internally in accordance with your organisation's policies.

### Why does a component such as musl show multiple licences?

Many open source projects are dual-licensed or contain mixed-licence files. SCANOSS reports
all detected licences.

### What remediation options exist for undeclared licences?

SCANOSS provides technical visibility into detected components and licences. You may
identify the upstream component, review official repository metadata, and document findings
in your SBOM. SCANOSS does not provide legal advice — licence compliance decisions should
be made internally or with appropriate legal counsel.

### Can specific copyleft licence findings be suppressed?

Yes. You may configure filtering rules in `scanoss.json`. Suppression affects reporting
output only — it does not remove the underlying detection or alter legal obligations.

```json theme={null}
{
  "filtering": {
    "exclude_license": ["GPL-2.0", "GPL-3.0"]
  }
}
```

### Can licensed dependency components be excluded from the SBOM?

Yes. You can configure exclusions in `scanoss.json` to omit certain paths from the
generated SBOM. This affects reporting output only and does not alter the underlying scan
results.

***

## Vulnerabilities

### Why are vulnerabilities not appearing in my report?

Check that:

* Vulnerability scanning is enabled.
* Your API key includes access to vulnerability data.
* You are using CycloneDX 1.4 or later for vulnerability output.
* The component has known vulnerabilities in the Knowledge Base.
* Your subscription tier includes vulnerability data access.

### How do I obtain vulnerability information in CycloneDX reports?

```bash theme={null}
scanoss-py scan --format cyclonedx -o sbom.cdx.json .
```

***

## Dependencies

### What causes dependency analysis errors?

Common causes include connectivity failures, unsupported package managers, or malformed
dependency files.

### Why is the package manager not captured?

Ensure supported package managers are used, file names are correct (case-sensitive on
Linux), and files are located in standard directories.

***

## SCANOSS Engine

### What is the SCANOSS Engine?

The SCANOSS Engine is the core scanning engine, implemented in C, with a Go-based REST API
layer.

* [SCANOSS Engine repository](https://github.com/scanoss/engine)
* [SCANOSS API repository](https://github.com/scanoss/api.go)

### What should I check if I encounter SCANOSS Engine installation issues?

* Linux compatibility
* Minimum 8 GB RAM recommended
* Sufficient disk space
* Required build dependencies installed

Refer to the Engine repository for full installation instructions.

***

## SCANOSS PAPI

### What is SCANOSS PAPI?

[SCANOSS PAPI](https://github.com/scanoss/papi) provides the public API contract
definitions for the SCANOSS platform.