Building an n8n community node usually goes wrong in a few predictable places: credentials that n8n doesn’t recognize, a node that never appears in the nodes panel, a missing or squashed icon, or UI changes that don’t show up. This guide collects the fixes from n8n’s official node troubleshooting page and the n8n-node CLI and linter docs, in the order you are likely to hit them. If you are just starting, read How to Build and Publish Your Own n8n Community Node first.
Quick fixes
| Symptom | Most likely cause |
|---|---|
| Credentials of type “*” aren’t known | The node’s credentials array uses a different name than the credential class |
| Node doesn’t show up in the nodes panel | The node isn’t registered in package.json |
| Icon missing | Wrong folder, wrong format, or icon without file: and the extension |
| Icon looks squashed or cut | SVG canvas not square, or PNG not 60×60 pixels |
| Description changes don’t appear after a refresh | The dev process has to be restarted |
| “API-Server can not be reached” | File, folder and class names don’t match, or displayOptions point at names that don’t exist |
| Linter keeps flagging a renamed file’s case (Windows) | A known Windows issue with case-only renames |
Error: Credentials of type “*” aren’t known
n8n matches credentials by name. The name property in your credential class and the name in the node’s credentials array must be exactly the same string. From n8n’s example, the credential class:
export class FriendGridApi implements ICredentialType {
name = 'friendGridApi';
displayName = 'FriendGrid API';
...
}and the node that uses it:
credentials: [
{
name: 'friendGridApi',
required: true,
},
],Note that it is the name value (friendGridApi) that has to match, not the class name (FriendGridApi) or the display name.
The node doesn’t show up in the nodes panel
n8n only loads nodes and credentials that are listed in your project’s package.json, under the n8n attribute. If you added a node file by hand, register it there. Projects created with npm create @n8n/node or n8n-node new set this up for you. Then check:
- You are running
npm run dev(orn8n-node dev) from the project root and opened the n8n it started atlocalhost:5678. - From n8n 3.0 the dev command runs n8n in a container, so Docker or Podman must be installed. With your own n8n instead, start it with
N8N_DEV_RELOAD=trueand runn8n-node dev --external-n8n. - The package name follows the required format:
n8n-nodes-<name>or@<scope>/n8n-nodes-<name>.
The node icon is missing or looks wrong
- Put the icon file in the same folder as the node.
- Use PNG or SVG.
- Reference it with the
file:prefix and the extension, for exampleicon: 'file:friendGrid.svg'. - For SVG, make the canvas square. For PNG, use 60×60 pixels.
Changes to the node description don’t appear
Changes to description properties (display names, parameters, options) don’t show when you only refresh the browser. Stop the running n8n-node dev process with Ctrl + C and start it again.
Error: There was a problem loading init data: API-Server can not be reached
n8n’s troubleshooting page lists two checks for this editor error:
- The node file, the node folder and the class must use matching names, and match the path registered in
package.json. - Every name used in a
displayOptionsproperty must be the name of a UI element (parameter) that exists in the node.
Linter problems
The linter (@n8n/eslint-plugin-community-nodes) checks node files, credential files and package.json. It runs after installing dependencies and before publishing, and in VS Code while you type.
npm run lintlists the issues;npm run lint:fixfixes the ones marked automatically fixable.- Don’t edit the generated
eslint.config.mjs; it comes from@n8n/node-cli. - If a rule is wrong for one line, use VS Code’s Quick fix > Disable {rule} for this line, and only with good reason. If you think the linter is wrong, n8n asks you to report it in the n8n repository.
- On Windows, renaming a file by changing only its letter case can leave the linter warning about file name case. That is a known Windows issue, not a problem in your code.
Checks before you submit for verification
If you plan to submit your node to n8n, run the community package scanner as well. The verification guidelines require it to pass:
npx @n8n/scan-community-package n8n-nodes-PACKAGEVerified nodes also can’t use run-time dependencies or read environment variables or files, and must be published from GitHub Actions with provenance. See Verified vs Unverified n8n Community Nodes.
After publishing: problems on the user side
Once your package is on npm, users install it as described in How to Install n8n Community Nodes. The settings that decide whether it can be installed at all, such as N8N_UNVERIFIED_PACKAGES_ENABLED, are in the environment variable reference. Your package then appears on communitynodes.com after our daily npm sync, with its downloads and release history.
FAQ
Why does n8n say my credential type isn’t known?
The name in the node’s credentials array doesn’t match the name property of your credential class.
Why doesn’t my custom node appear in n8n?
Most often it isn’t registered under the n8n attribute in package.json, or you are looking at a different n8n than the one npm run dev started.
What size should an n8n node icon be?
PNG at 60×60 pixels, or an SVG with a square canvas, in the node’s folder and referenced as file:name.svg or file:name.png.
Why don’t my parameter changes show up?
Restart n8n-node dev. Description changes need a restart, not just a browser refresh.