Seed Project

The CLI prints its log file location when it starts. Use that log together with the failing command and configuration to diagnose setup, download, and build errors.

ℹ️ For details on failures specific to automated tests, see the Testing > Troubleshooting section.

Errors such as SELF_SIGNED_CERT_IN_CHAIN or unable to verify the first certificate can occur when a corporate proxy signs HTTPS traffic with an internal certificate authority that Node.js doesn't trust. Obtain the required CA certificates from your organization and configure trust before retrying the command.

System Certificates

Upgrading Node.js alone doesn't enable trust in system certificates. With Node.js v22.19.0, v24.6.0, or later supported versions, enable the system CA store explicitly.

On Windows, set the environment variable in PowerShell before running setup:

$env:NODE_USE_SYSTEM_CA = "1"
npm run setup

On macOS, set it for the command:

NODE_USE_SYSTEM_CA=1 npm run setup

For repeated use, configure the variable in your user environment or shell profile and restart the terminal. The equivalent Node.js flag is --use-system-ca, which can be added to NODE_OPTIONS while preserving existing options.

Additional Certificates

To supply CA certificates directly, use NODE_EXTRA_CA_CERTS with a PEM file containing the required certificate chain.

On Windows:

$env:NODE_EXTRA_CA_CERTS = "C:\Certificates\company-ca.pem"
npm run setup

On macOS:

NODE_EXTRA_CA_CERTS="$HOME/certificates/company-ca.pem" npm run setup

ℹ️ For details on CA configuration and supported versions, see the Node.js enterprise network documentation.

Temporary Verification Bypass

⚠️ Note that disabling certificate verification allows untrusted HTTPS connections. Use a bypass only to diagnose a development environment, then restore verification and configure the required certificates. Don't save the bypass in a user profile or CI configuration.

To test a single setup attempt in PowerShell and restore the previous value afterwards:

$previousTlsSetting = $env:NODE_TLS_REJECT_UNAUTHORIZED
try {
    $env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
    npm run setup
} finally {
    $env:NODE_TLS_REJECT_UNAUTHORIZED = $previousTlsSetting
}

On macOS, scope the bypass to the command:

NODE_TLS_REJECT_UNAUTHORIZED=0 npm run setup

Connection timeouts, ECONNREFUSED, or fetch failed errors can indicate a missing proxy configuration. Successful access in a browser doesn't establish that the CLI has the same proxy configuration.

Available since @interopio/iocd-cli 0.0.54

The CLI reads HTTP_PROXY, HTTPS_PROXY, and NO_PROXY, including their lowercase equivalents. It doesn't discover Windows WinHTTP or macOS system proxy settings.

The following example demonstrates proxy settings for a PowerShell session:

$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,.example.com"
npm run setup

On macOS:

export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.example.com"
npm run setup

Use the proxy address and exclusions supplied by your organization. Confirm that the variables are present in the terminal or CI job that runs the CLI. Retry setup and check the CLI log. If connections succeed but certificate validation fails, configure the CA certificates described in Certificate Errors.

NPM honors proxy environment variables. It also has registry, proxy, and certificate settings that can override or supplement the environment. If npm install fails while component downloads work, inspect the relevant NPM settings:

npm config get registry
npm config get proxy
npm config get https-proxy
npm config get cafile
npm config get strict-ssl

To use explicit NPM proxy settings, execute:

npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

To configure a CA file for NPM, execute the appropriate command for your operating system:

npm config set cafile "C:\Certificates\company-ca.pem"

npm config set cafile "$HOME/certificates/company-ca.pem"

If your organization provides an internal registry, configure it as directed by your administrator. The following commands demonstrate a default registry and a registry for the @interopio scope:

npm config set registry https://registry.example.com/
npm config set @interopio:registry https://registry.npmjs.org/

Verify that the selected registry serves the required packages. HTTP 400 responses can also come from a proxy or registry policy, so inspect the NPM log before changing certificate settings.

For a temporary development diagnostic, NPM accepts npm install --strict-ssl=false. This disables certificate checking for that invocation. Restore normal verification and configure the CA file before continuing regular work.

ℹ️ For details on NPM proxy, registry, and CA settings, see the NPM configuration documentation.

If a build fails with Packaging requires an active io.Connect Desktop license, the rest of the message states why the license was rejected. Provide a valid key in config/iocd.license.key or via IOCD_LICENSE_KEY. Ensure that the variable is available in the process executing the command.

Verify that signtool.exe is available on PATH, the certificate is valid, and its password is correct. Configure exactly one of "pfxPath" or "certificateSha1". If the command isn't found, install the Windows SDK or use an environment that includes its tools.

ℹ️ For details on certificates and signing Squirrel executables, see the Code Signing > Windows section.

Use an app-specific Apple ID password, verify your Apple Developer Program membership, and check that "appleTeamId" identifies the correct team. Inspect the notarization output for the rejected file or signing issue.

ℹ️ For details on configuring credentials, see the Code Signing > macOS > Notarization section.

Run npm run setup, confirm that /components/iocd exists, and start required custom apps with npm run apps-dev. Check the CLI and platform logs for invalid configuration, unavailable app URLs, or license failures.

Check network connectivity and the "components.store" settings in config/iocd.cli.config.json. For a GitHub store, verify access to the configured repository. For a local store, verify the configured path and downloaded component files. Use the proxy and certificate guidance if the log reports network or TLS errors.