n8n-nodes-convex

Community node for connecting n8n to Convex.

This package lets you use n8n with:

• Convex database functions
• Convex storage operations
• self-hosted Convex deployments
• custom Convex backend functions

What This Repository Contains

• the n8n community node package
• Convex helper code examples
• setup and troubleshooting documentation

Quick Start

There are two parts to make this work:

1. install this package in n8n
2. add and deploy the required functions in your Convex app

If you only do one of those, the node will not fully work.

Install The Node

From this repository:

npm install
npm run build
npm pack

This creates a package file such as:

n8n-nodes-convex-0.1.0.tgz

Install Into n8n

Docker

Copy the tarball into the container:

docker cp n8n-nodes-convex-0.1.0.tgz n8n:/home/node/

Install it:

docker exec -it n8n sh -c "cd /home/node && npm uninstall n8n-nodes-convex; npm install ./n8n-nodes-convex-0.1.0.tgz"

Restart n8n:

docker restart n8n

Docker Compose

Restart after install:

docker compose restart n8n

systemd

sudo systemctl restart n8n

Create The Credential In n8n

In n8n:

1. add a Convex node
2. create a new Convex API credential
3. enter your Convex deployment URL
4. enter your deploy key or admin key
5. click Test

If the test passes, authentication is working.

Required Convex Backend Setup

The storage and database helpers used by the node must exist in your Convex app.

At minimum, add the helper file in your Convex project:

convex/n8n_nodes_convex.ts

Then deploy it:

npx convex deploy

If you do not deploy the backend functions, you will get errors like:

Could not find public function for 'n8n_nodes_convex:n8nListFiles'

Full Setup Tutorial

See SETUP.md for the full step-by-step guide, including:

• full Convex backend code
• schema setup
• deployment steps
• testing steps
• common error fixes

Typical Update Flow

Whenever you change this node package:

npm run build
npm pack

Then reinstall it in n8n and restart n8n.

If you changed the Convex backend functions too, also redeploy the Convex app:

npx convex deploy

Troubleshooting

Authorization failed

Usually means one of these:

• wrong deployment URL
• wrong key
• n8n is still using an older installed build

Node does not have access to the credential

Usually means one of these:

• the credential is not attached to the node
• the credential was created before reinstalling the node
• the workflow needs the credential re-selected and saved

Could not find public function

Usually means one of these:

• convex/n8n_nodes_convex.ts is missing
• the function names do not match
• you forgot to run npx convex deploy

Repository Files

• README.md: quick start and overview
• SETUP.md: full setup tutorial
• credentials/ConvexApi.credentials.ts: credential definition
• nodes/Convex/: node implementation
• convex/n8n_nodes_convex.ts: helper Convex functions example

License

This project is licensed for personal, non-commercial use only.

For commercial licensing inquiries, contact mamaspace@motion.ninja.