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

# Qualitizer reference

> Run the Qualitizer web application to understand, troubleshoot, and improve the quality of your CDF deployment — with insights into access groups, data models, and job scheduling.

The **Qualitizer** is a web application — a collection of tools that help you understand, troubleshoot, and improve the quality of your Cognite Data Fusion deployment. It surfaces insights into access, data models, and workload scheduling that are otherwise hard to see, and it ships with built-in help pages that explain each feature. Qualitizer is available in English and Japanese.

The application helps you answer questions such as:

* "Why does user X see this search result while user Y does not?" — full insight into your CDF groups makes it easy to spot where you can optimize and reuse access.
* Where are failing activities and processing bottlenecks? — identify workload spikes so you can reduce them and improve system stability.
* What do my data model views and properties look like? — inspect the structure of your data models.

<Note>
  Qualitizer is built on the [Cognite Flows](/cdf/flows/index) application framework. The tool is run in standalone mode with a local proxy that injects client-credentials tokens, so technical users can run it on their own machine.
</Note>

<Note>
  This is the same Qualitizer tool that the [Foundation](/cdf/deploy/cdf_toolkit/references/packages/foundation) deployment pack can install (the `qualitizer` module). If you already installed it through Foundation, you can run it from that project's `modules/tools/apps/qualitizer/` folder instead of cloning it separately.
</Note>

## Who it's for

**Target personas:**

* **Data engineers** — investigate data quality, access, and workload issues on a CDF project.
* **CDF administrators** — review access groups, data models, and job scheduling.

**Use this tool when:**

* You need to understand why users see different search or access results and want a clear view of your CDF groups.
* You want to find failing activities and scheduling bottlenecks to improve system stability.
* You want to inspect the views and properties of your data models.

## Prerequisites

Verify all of the following before you start:

* Cognite Toolkit version **0.8 or later** is installed. See [Setting up](/cdf/deploy/cdf_toolkit/guides/setup).
* A `cdf.toml` file exists in your project root. If it is missing, run `cdf modules init` and select **Create toml file (required)**.
* Authentication is configured and verified — run `cdf auth init` and `cdf auth verify` using a local `.env` file. See [Authentication and authorization](/cdf/deploy/cdf_toolkit/guides/auth).
* Node.js **22 or later** and npm are installed to run the Qualitizer web application and its proxy.
* You have permission to enable feature flags in your CDF project. Contact your CDF administrator if you do not have access.

## Install

You can install Qualitizer with the Cognite Toolkit or by cloning the best-practices GitHub repository.

<Tabs>
  <Tab title="Cognite Toolkit">
    Run `cdf modules add` and select **Tools and Accelerators > CDF Qualitizer Application**.

    The Toolkit creates the module under `modules/tools/apps/qualitizer/`.
  </Tab>

  <Tab title="Clone from GitHub">
    Clone the [Cognite Library repository](https://github.com/cognitedata/library) and work directly in the `modules/tools/apps/qualitizer/` folder:

    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    git clone https://github.com/cognitedata/library
    cd library/modules/tools/apps/qualitizer
    ```
  </Tab>
</Tabs>

## Run the application

Qualitizer runs as two local processes: a web application you open in the browser, and a proxy that handles authentication against CDF.

<Note>
  The tool does not store state. For some views, this limits the time window you can inspect at once (for example, one hour).
</Note>

<Steps>
  <Step title="Set up the .env file">
    You can reuse the `.env` file from your Toolkit setup. Copy it into the `qualitizer` folder and add these two lines:

    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    CDF_PROXY_URL=http://localhost:4243
    CDF_BROWSER_URL=<my-project>.fusion.cognite.com
    ```

    The complete list of environment variables is in the README file included with the tool. See [Configuration reference](#configuration-reference) for the most common ones.
  </Step>

  <Step title="Start the proxy">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cd <toolkit_folder>/modules/tools/apps/qualitizer/
    npm install
    npm run proxy
    ```

    Leave this process running and open a separate terminal for the next step.
  </Step>

  <Step title="Start the web server">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cd <toolkit_folder>/modules/tools/apps/qualitizer/
    npm run standalone
    ```

    Open [http://localhost:4242/](http://localhost:4242/) in your browser.
  </Step>
</Steps>

## Configuration reference

Set these environment variables in the `.env` file in the `qualitizer` folder. The full list is in the README included with the tool.

| Variable            | Description                                                                                          | Default                       |
| ------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------- |
| `CDF_PROJECT`       | CDF project URL name.                                                                                | —                             |
| `CDF_PROXY_URL`     | Proxy base URL used by the web application in standalone mode.                                       | `http://localhost:4243`       |
| `CDF_BROWSER_URL`   | Fusion UI base URL for transformation preview links.                                                 | `https://fusion.cognite.com`  |
| `CDF_URL`           | CDF base URL.                                                                                        | `https://api.cognitedata.com` |
| `IDP_TOKEN_URL`     | OAuth token endpoint (client credentials) used by the proxy for token exchange.                      | —                             |
| `IDP_CLIENT_ID`     | IdP application client ID.                                                                           | —                             |
| `IDP_CLIENT_SECRET` | IdP application client secret used by the proxy.                                                     | —                             |
| `IDP_SCOPES`        | OAuth scopes.                                                                                        | `${CDF_URL}/.default`         |
| `PROXY_INSECURE`    | Skip certificate validation. Safe only because the proxy runs on localhost in a trusted environment. | `true`                        |

## Troubleshooting

| Symptom                                         | Likely cause                                                                                              | Resolution                                                                                                                   |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| The module does not appear in `cdf modules add` | `[library.cognite]` not configured in `cdf.toml`, or `[library.toolkit-data]` still present alongside it. | Replace `[library.toolkit-data]` with `[library.cognite]` in `cdf.toml`. The two sections cannot coexist.                    |
| The web application cannot reach CDF            | The proxy is not running, or `CDF_PROXY_URL` does not match the proxy port.                               | Start the proxy with `npm run proxy` and confirm `CDF_PROXY_URL` matches its address (default `http://localhost:4243`).      |
| Proxy fails to obtain a token                   | Incorrect IdP credentials or token endpoint in `.env`.                                                    | Verify `IDP_TOKEN_URL`, `IDP_CLIENT_ID`, `IDP_CLIENT_SECRET`, and `IDP_SCOPES` are set correctly for your identity provider. |
| Some views only show a short time window        | Expected behavior.                                                                                        | The tool does not store state, so some views are limited to short windows (for example, one hour).                           |

For issues not covered here, contact Cognite support.

## Support

| Field                  | Details                                                                     |
| ---------------------- | --------------------------------------------------------------------------- |
| Team                   | Cognite Value Delivery Team                                                 |
| Documentation          | [Cognite product documentation](/)                                          |
| Questions and feedback | [Deployment Packs group on Cognite Hub](https://hub.cognite.com/groups/578) |
| Version                | 1.0.0                                                                       |
| Last updated           | 2026                                                                        |