Skip to main content

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.

This guide is for developers building Flows custom apps. Before you begin, make sure you have a Flows custom app created and dependencies installed. See Getting started with Flows custom apps. npm run dev serves your app over HTTPS so CDF can embed it in an iframe. Without a trusted certificate, the browser blocks the embed and shows Not Secure or “the webpage at https://localhost:3001/ might be having issues”. You need to establish trust between your browser and the local dev server before CDF can load your app. You can establish trust in two ways:
1

Install the mkcert binary

Run the following command in your terminal:
brew install mkcert
If you don’t have a package manager, download the binary directly from the mkcert installation guide.
2

Run setup-https

npx @cognite/cli@latest apps setup-https
This command adds the mkcert Certificate Authority (CA) to your system trust store and issues a certificate for localhost, local.cognite.ai, and *.local.cognite.ai.
You must accept the sudo or UAC prompt when it appears.
3

Restart the dev server and browser

Stop npm run dev, restart it, then fully quit and reopen your browser so it re-reads the trust store. The address bar should show the lock icon.

​
Accepting the certificate manually (no admin required)

If you don’t have admin access, manually trust the dev server’s self-signed certificate in your browser:
1

Start the dev server

Run the following command in your terminal:
npm run dev
The URL is displayed in the terminal (for example, https://localhost:3001).
2

Open the localhost URL in a new tab

Open a new tab in your browser and paste the URL. The browser shows a privacy warning:
Select Advanced → Proceed to localhost (unsafe).
Your app should load in the new tab.
3

Reload CDF

Reload the CDF tab to see the app load without warnings.
Install mkcert to avoid repeating this step.Without mkcert, the dev server generates a new certificate on every start, so the browser warning returns on every restart, port change (for example, 3002 instead of 3001), or browser switch.

​
Troubleshooting

Symptom:
  • Running npx @cognite/cli@latest apps setup-https fails with mkcert is not installed.
Cause:
  • The CLI cannot find mkcert on your PATH.
Resolution:
Symptom:
  • The browser shows Not Secure even after apps setup-https completed successfully.
Cause:
  • The browser cached the old trust store state and hasn’t re-read it yet.
Resolution:
  • Fully quit and reopen the browser.
  • On Windows, close Edge from the system tray, not just the window.
Symptom:
  • The CLI reports that the apps setup-https command doesn’t exist.
Cause:
  • Your local version of @cognite/cli is older than 1.4.0, which is when the command was added.
Resolution:
  • Run the command with @latest to bypass any pinned version:
npx @cognite/cli@latest apps setup-https
  • If @latest still resolves to a version older than 1.4.0, delete any .npmrc in the current directory that pins a registry or version.
Symptom:
  • Each npm run dev start uses a higher port number.
Cause:
  • An orphaned node process from a previous session is still holding the port.
Resolution:
  • Find and stop the process. You can only stop processes you own.
# macOS / Linux
lsof -i :3001 # Checks what's running on port 3001
kill -9 <PID> # Stops the process

# Windows
Get-Process -Id (Get-NetTCPConnection -LocalPort 3001).OwningProcess
Stop-Process -Id <PID> -Force

​
Further reading

Last modified on May 28, 2026