Troubleshooting

This section contains information that can help you troubleshoot problems.

Docker image paths

Path	Description
`/data/project`	Root directory of the project to be analyzed
`/data/results`	Directory to store the analysis results
`/opt/idea`	Directory containing the IDE distribution
`/root/.config/idea`	Directory where the IDE contains configuration
`/data/profile.xml`	Used if a profile was not previously configured either via the CLI or the `qodana.yaml` file.

For Maven and Gradle projects, Qodana uses the following directories to access third-party libraries:

Path	Description
`/data/cache/.m2`	Maven project dependencies
`/data/cache/gradle`	Gradle project dependencies

Mounting these directories saves Qodana from downloading all dependencies again while using these linters:

List of files for investigating Qodana behavior

There are several options for examining Qodana behavior using the /data/results directory:

The /data/results/projectStructure/Modules.json file lists all modules detected by Qodana. It should be identical to the list that you expect to see while opening the project in IDEA. If this is no longer the case, check pom.xml for Maven or the build.gradle file for Gradle configurations.
In the /data/results/ directory, each inspection that detected a possible problem creates its own file named ID.json, where ID is the inspection name that can be used in qodana.yaml for including or excluding inspections. You can find the complete list of inspection IDs in the /data/results/.descriptions.json file using the /groups/*/inspections/*/shortName pattern.
In /data/results/log/idea.log, you can investigate suspicious warnings.

IP addresses required by Qodana Cloud

To provide the correct work of the contributor counting functionality, add the IP address range 54.76.32.8/32 to a list of allowed inbound connections on your side.

Severity levels

This table shows the relation between severities in JetBrains IDEs, SARIF files, and Qodana reports.

IDE severity	SARIF severity	Qodana report severity	Code Climate severity	Bitbucket severity
ERROR	ERROR	Critical	Blocker	High
WARNING	WARNING	High	Critical	High
WEAK WARNING	NOTE	Moderate	Major	Medium
TYPO	NOTE	Low	Minor	Low
INFORMATION	NOTE	Info	Info	Info
OTHER	NOTE	Info	Info	Info

Error messages about missing files, packages, modules, or classes

During inspections, Qodana may report about missing files, packages, modules, or classes. In this case, you need to have your project prepared for code inspection. For example, you can create a script and configure Qodana for running it as shown in the Prepare your project section.

Disable a specific inspection for a specific file

To disable inspections for a specific file, in the project root save the qodana.yaml file containing this configuration:

            exclude:
              - name: <inspection-name>
            paths:
              - <path/to/the/file/from/project/root>
        

You can also suppress the inspection only for a class by adding the noinspection comment above the class:

            // noinspection <inspection-name>
            export class WorkflowJobSubject {
                private static subject: Observable<GithubEvent<WorkflowJobEvent>> | null =
                    null;
            private static GithubWebhookEventSubject: any;
        

Inspect a specific project directory within a repository

A typical project structure can have a directory structure similar to this:

            repo/
            .git/
            project/
            ...
        

Here, the repo/.git directory contains information that should be accessible to Qodana, and the repo/project directory contains the project that needs to be inspected by Qodana. All these samples mount the repo/project directory using the --project-dir option, while the QODANA_TOKEN variable refers to the Qodana Cloud project token:

                    docker run \
                    -v repo/:/data/project/ \
                    -e QODANA_TOKEN="<cloud-project-token>" \
                    jetbrains/qodana-<linter> \
                    --project-dir=/data/project/project/
                

                    qodana scan \
                    -e QODANA_TOKEN="<cloud-project-token>" \
                    --project-dir=/data/project/project/
                

                    name: Qodana
                    on:
                        workflow_dispatch:
                        pull_request:
                        push:
                            branches:
                                - main
                                - 'releases/*'

                    jobs:
                        qodana:
                            runs-on: ubuntu-latest
                            permissions:
                                contents: write
                                pull-requests: write
                                checks: write
                            steps:
                                - uses: actions/checkout@v3
                                  with:
                                      ref: ${{ github.event.pull_request.head.sha }}  # to check out the actual pull request commit, not the merge commit
                                      fetch-depth: 0  # a full history is required for pull request analysis
                                - name: 'Qodana Scan'
                                  uses: JetBrains/qodana-action@v2024.3
                                  with:
                                      args: --project-dir,project
                                  env:
                                    QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
                

Run Qodana behind a proxy server

Depending on your needs, you can run Qodana behind a proxy server using an existing Qodana Docker image, or create a Docker image from scratch.

Follow these steps to prepare an existing Qodana Docker image to run behind a proxy server:

Create the proxy.settings.xml file and save it in the .qodana directory of your project root.
In the proxy.settings.xml file, save information about the proxy server:
<application> <component name="HttpConfigurable"> <option name="USE_HTTP_PROXY" value="true" /> <option name="PROXY_HOST" value="<ProxyHost>" /> <option name="PROXY_PORT" value="<ProxyPort>" />  </component> </application>
In the qodana.yaml file, save this boostrap command that will copy the proxy.settings.xml file to a Qodana Docker image:
boostrap: cp .qodana/proxy.settings.xml /root/.config/idea/options/proxy.settings.xml

To create your custom Qodana image containing proxy server settings, follow this procedure:

Create the proxy.settings.xml file and include the proxy server information in it:
<application> <component name="HttpConfigurable"> <option name="USE_HTTP_PROXY" value="true" /> <option name="PROXY_HOST" value="<ProxyHost>" /> <option name="PROXY_PORT" value="<ProxyPort>" />  </component> </application>
Use this sample to create Dockerfile:
FROM docker.io/jetbrains/qodana-<linter>:2024.3 LABEL version="1.0.0" ##Copy the proxy.settings.xml file COPY proxy.settings.xml /root/.config/idea/options/proxy.settings.xml ##Copy the gradle.properties file (optional) COPY gradle.properties ~/.gradle/gradle.properties ##Install certificates COPY <your_certificate> <path_to_certificate> RUN $JAVA_HOME/bin/keytool -import -trustcacerts -alias dc-ca -keystore $JAVA_HOME/lib/security/cacerts -noprompt -storepass changeit -file <path_to_certificate> COPY <your_certificate> /etc/ssl/certs RUN chmod 444 /etc/ssl/certs/<your_certificate> ##Set proxy ENV http_proxy <proxy> ENV https_proxy <proxy> ENV HTTP_PROXY <proxy> ENV HTTPS_PROXY <proxy> ENV ftp_proxy $http_proxy ENV dns_proxy $http_proxy ENV rsync_proxy $http_proxy

List of exit codes

Qodana provides the following exit codes:

Exit code	Description
`7`	The EAP license of a linter has expired. Please change the Docker tag either to the next EAP version like `20xx.x-eap` or to a stable version like `20xx.x`.
`137`	Qodana or Docker has crashed due to excessive memory usage. Please increase the amount of RAM available for Docker.
`255`	The number of problems detected by Qodana exceeds a threshold configured by a quality gate.

Last modified: 15 January 2025