Skip to main content

Troubleshooting

Start by checking the active environment:

n8nac env list
n8nac env status
n8nac workspace status

Connection And Authentication​

Cannot connect to n8n​

Verify the URL:

curl -I https://your-n8n-instance.com

Refresh the local API key for the environment:

n8nac env auth set <environment> --api-key-stdin

Invalid API key​

  • Regenerate the key in n8n Settings -> API.
  • Store it again with n8nac env auth set <environment> --api-key-stdin.
  • Confirm the API key has access to the selected project.

Self-signed certificate or private CA​

Symptom: unable to verify the first certificate, self-signed certificate in certificate chain, or UNABLE_TO_GET_ISSUER_CERT_LOCALLY when connecting to an HTTPS instance.

Point n8n-as-code at the PEM bundle that holds your root CA:

export NODE_EXTRA_CA_CERTS=/path/to/root-ca.pem

N8NAC_EXTRA_CA_CERTS works the same way and accepts several paths separated by the platform path delimiter, a comma, or a newline.

Certificates are verified for every public host name. Verification is relaxed only for an instance on the loopback interface or a private network (localhost, 127.0.0.0/8, ::1, 10/8, 172.16/12, 192.168/16, 100.64/10, *.local, *.internal, *.home.arpa, or a single-label intranet name) that you have not configured a CA for, because a public CA cannot issue a certificate for those. Configuring a CA turns verification on for those hosts too.

If your instance serves a private certificate on a public host name, add its CA with one of the settings above. Only as a last resort, N8NAC_INSECURE_TLS=1 skips verification entirely — it makes the connection, and the API key it carries, interceptable by anyone on the network path.

In the VS Code extension the environment variable is often not enough. The extension host is an Electron process: it ignores NODE_EXTRA_CA_CERTS and cannot be started with Node's --use-system-ca flag, which is why n8nac succeeds in the terminal while auto-load fails. Set the bundle in your VS Code settings instead — relative paths resolve against the workspace folder — and reload is not required:

{
  "n8n.tls.certificateAuthorities": ["/path/to/root-ca.pem"]
}

If the root CA is only reachable from the operating system trust store, set "n8n.tls.useSystemCertificateAuthorities": true as well. It is off by default because the OS store holds hundreds of anchors that are re-applied to every TLS handshake, and it needs a host running Node 22.15 or newer.

The n8n-as-code output channel lists every anchor that was loaded and every bundle that could not be read.

An environment sees another account's workflows​

This happens when two environments point at the same base URL and only one of them has its own key.

n8nac env status <environment> --json

apiKeySource tells you which key is in use. workspace-local or global means the environment falls back to a key shared with the other environments on that URL. Give it its own key:

n8nac env auth set <environment> --api-key-stdin

workspace-environment confirms the environment authenticates with its own key.

Missing Configuration​

n8nac-config.json not found​

Create an environment:

n8nac env add Dev --base-url <url> --workflows-path workflows/dev
n8nac env auth set Dev --api-key-stdin
n8nac env use Dev

Or attach a local managed instance:

n8n-manager instance list
n8nac env add Local --managed-instance <id> --workflows-path workflows/local
n8nac env use Local

VS Code Extension​

Workflows do not load​

  • Confirm the workspace has an environment in n8n environments.
  • Confirm the remote environment has a local API key.
  • Refresh the n8n sidebar.
  • Check the n8n-as-code Output panel.

Canvas does not show​

  • Verify the n8n URL in the active environment.
  • Confirm the API key is valid.
  • Reopen the split view.

Unsupported workspace config version​

Only V4 workspace environment configs are supported. Recreate the workspace environment explicitly:

n8nac env add Dev --base-url https://n8n.example.com --workflows-path workflows/dev
n8nac env auth set Dev --api-key-stdin
n8nac env use Dev
n8nac env status --json

Sync Issues​

Push or pull fails with conflict​

Both sides changed since the last synced base.

n8nac resolve <workflow-id> --mode keep-current
n8nac resolve <workflow-id> --mode keep-incoming

In VS Code, use the conflict actions in the tree.

Changes made in n8n UI are not local​

n8nac list
n8nac pull <workflow-id>

Push rejected by OCC​

The remote changed since your last pull. Pull first or resolve the conflict intentionally.

Managed Local Instances​

Local managed instances are local machine resources. They are not created or deleted by n8nac env remove.

n8n-manager instance list
n8n-manager instance start <id>
n8n-manager instance stop <id>
n8n-manager tunnel start <id>
n8n-manager tunnel stop <id>

If a workspace environment references a missing local managed instance, recreate it or point the environment to a remote n8n URL:

n8nac env update <environment> --base-url <url>
n8nac env auth set <environment> --api-key-stdin

Claude Plugin​

Plugin not recognized​

Install with the full HTTPS marketplace URL:

/plugin marketplace add https://github.com/EtienneLescot/n8n-as-code
/plugin install n8n-as-code@n8nac-marketplace

Restart Claude Code after installation.

Claude lacks n8n context​

n8nac update-ai

Confirm AGENTS.md exists and points to the generated skills.

OpenClaw Plugin​

Setup fails​

openclaw plugins install @n8n-as-code/n8nac
openclaw n8nac:setup
openclaw gateway restart

If you migrated from the old package name, uninstall it first:

openclaw plugins uninstall n8nac
openclaw plugins install @n8n-as-code/n8nac

CLI Package Conflicts​

If n8nac --help shows old commands, remove the deprecated package:

npm uninstall -g @n8n-as-code/cli
n8nac --version
n8nac --help

The current package is n8nac.

Complete Reset​

Back up workflows first, then recreate the environment:

cp -r workflows workflows-backup-$(date +%Y%m%d)
rm n8nac-config.json
n8nac env add Dev --base-url <url> --workflows-path workflows/dev
n8nac env auth set Dev --api-key-stdin
n8nac env use Dev
n8nac list

Still Stuck​

Include this output when asking for help:

n8nac --version
node --version
n8nac env list
n8nac env status
n8nac workspace status