5. Common Issues and Solutions

Action Not Triggering

Problem: You type a message but the action doesn't respond.

Likely causes:

• The action isn't registered (forgot to add runtime.registerAction())

• The validate function returns false for your test input

• Another action is catching the message first

How to debug: 

Test your VeChain function separately - Run the VeChain SDK function in isolation to verify it works before testing the full action.

Check your action setup in src/index.ts:

• Verify the action is registered: runtime.registerAction(yourAction)

• Check for duplicated keywords in similes across multiple actions

• Ensure all required parameters are present (name, similes, description, validate, handler, examples)

VeChain Connection Fails

Problem: Getting "Failed to fetch balance" or similar errors.

Likely causes:

• Wrong node URL in .env

• Invalid address format

How to fix:

1. Check your .env has the correct VECHAIN_NODE_URL

2. Try the URL in your browser - you should see JSON data

3. Verify the address is a valid VeChain wallet address 

Dependencies Missing

Problem:Cannot find module '@vechain/sdk-network' or similar.

Solution:

# Install the VeChain SDK
npm install @vechain/sdk-network

If the error persists:

# Clean install
rm -rf node_modules package-lock.json
npm install

# Or with bun
rm -rf node_modules
bun install

Build Errors

Problem: TypeScript compilation errors when running bun run build.

Common causes:

• Missing type definitions

• Syntax errors in your code

• Import paths are wrong (should be relative, like '../vechain/balance')

How to fix: Read the error message carefully - TypeScript usually tells you exactly what's wrong and where. Fix that file and run build again.