Copy page

Local Development

Troubleshooting

Changing the port numbers

By default the Zuplo local server runs on port 9000, the route designer runs on port 9100, and the docs server runs on port 9200. To change any of these port numbers, you can call

Code
npx zuplo dev --port <port number> --editor-port <editor port number> --docs-port <docs port number>

Each flag is independent, so you only need to pass the one for the port you want to change. For example, if port 9200 is already in use, you can move just the docs server:

Code
npx zuplo dev --docs-port 9201

Certificates Errors

When running Zuplo locally you may want to call a service with a self-signed certificate. By default this isn't supported - we recommend using signed/trusted certificates in deployed environments. However, for local development you can ignore certificate errors by adding the --unsafely-ignore-certificate-errors flag on the zuplo dev command.

Run your development server with the following command:

Code
npx zuplo dev --unsafely-ignore-certificate-errors

If you want to update your package.json to always allow self-signed certificates, you can add the following script:

Code
{
  "scripts": {
    "dev": "zuplo dev --unsafely-ignore-certificate-errors"
  }
}

mTLS client certificates don't load

On managed-dedicated and self-hosted projects, zuplo dev loads client certificates from .zuplo-local/mtls/<cert-name>/tls.crt and tls.key, or from the directory passed to --mtls-certs. If the startup output reports no loaded certificates, check the warnings listed in Local certificates fail to load.

Local mTLS isn't available on managed-edge projects.

"unknown format ... ignored" warnings

When the development server prints warnings like unknown format "date-time" ignored in schema at path "…", your OpenAPI schema uses a format keyword that the validator does not actively check. These warnings are safe to ignore — they do not stop the server or change validation behavior. See OpenAPI Format Validation Warnings for details.

Updating the Zuplo CLI

To update the CLI, run the following command in your project directory.

Code
npm install zuplo@latest

You must include the @latest to ensure you are getting the latest. Otherwise, you could have an older version cached locally on your machine.

You can compare if you have the latest version by looking at the version number on NPM

Getting help

Please reach out to support@zuplo.com or join our Discord server.