Skip to main content
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:
If you don’t have a package manager, download the binary directly from the mkcert installation guide.
2

Run 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:
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).
The new tab will appear blank or show a “The webpage at https://localhost:3001 might be having issues” message as the app only renders within the CDF iframe, not in a standalone window. You can close this tab.
3

Reload CDF

Return to the CDF tab and reload. If the iframe doesn’t load immediately, reload again and wait a few seconds for the now-trusted session to register.
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:
  • 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.

​
Further reading

Last modified on May 29, 2026