Error Codes

Common errors and how to resolve them.

Gateway Errors

TRIK_NOT_FOUND

Error: Trik 'xyz' not found
Code: TRIK_NOT_FOUND

Cause: The specified trik is not loaded in the gateway.

Solution:

1. Check the trik ID spelling
2. Ensure the trik is in .trikhub/config.json
3. Run trik list to see installed triks
4. Load the trik: await gateway.loadTrik('./path/to/trik')

ACTION_NOT_FOUND

Error: Action 'xyz' not found in trik 'abc'
Code: ACTION_NOT_FOUND

Cause: The action doesn’t exist in the trik’s manifest.

Solution:

1. Run trik info <trik> to see available actions
2. Check spelling of action name
3. Verify manifest.json has the action defined

INVALID_INPUT

Error: Invalid input for action 'search'
Code: INVALID_INPUT

Cause: Input doesn’t match the action’s inputSchema.

Solution:

1. Check the inputSchema in manifest.json
2. Ensure required fields are present
3. Verify types match (string, integer, etc.)

Example:

// Schema requires 'topic' as string
const result = await gateway.execute('demo/article-search', 'search', {
  topic: 'AI'  // Correct
  // topic: 123  // Wrong: number instead of string
});

INVALID_OUTPUT

Error: Invalid output from trik
Code: INVALID_OUTPUT

Cause: Trik returned data that doesn’t match declared schema.

Solution:

1. Check your graph.ts returns correct structure
2. Verify agentData matches agentDataSchema
3. Verify userContent matches userContentSchema

EXECUTION_TIMEOUT

Error: Trik execution timed out
Code: EXECUTION_TIMEOUT

Cause: Trik exceeded maxExecutionTimeMs.

Solution:

1. Increase limits.maxExecutionTimeMs in manifest
2. Optimize trik code
3. Check for infinite loops or blocking operations

SESSION_EXPIRED

Error: Session expired
Code: SESSION_EXPIRED

Cause: Session exceeded maxDurationMs.

Solution:

1. Start a new session (don’t pass sessionId)
2. Increase capabilities.session.maxDurationMs

SESSION_NOT_FOUND

Error: Session not found
Code: SESSION_NOT_FOUND

Cause: Session ID doesn’t exist or was deleted.

Solution:

1. Don’t pass sessionId for first request
2. Store and reuse sessionId from responses
3. Handle session errors by starting fresh

CLI Errors

NOT_AUTHENTICATED

Error: Not authenticated. Run 'trik login' first.
Code: NOT_AUTHENTICATED

Cause: Trying to publish without authentication.

Solution:

trik login

TRIK_NOT_INSTALLED

Error: Trik '@xyz/abc' is not installed
Code: TRIK_NOT_INSTALLED

Cause: Trying to uninstall or upgrade a trik that isn’t installed.

Solution:

trik list           # Check installed triks
trik install @xyz/abc  # Install first

VERSION_EXISTS

Error: Version 1.0.0 already exists
Code: VERSION_EXISTS

Cause: Trying to publish a version that’s already published.

Solution:

1. Increment version in manifest.json
2. Use trik publish -t <new-version>

INVALID_MANIFEST

Error: Invalid manifest.json
Code: INVALID_MANIFEST

Cause: Manifest doesn’t meet requirements.

Solution:

1. Validate required fields: id, name, version, actions, entry
2. Check JSON syntax
3. Run trik validate ./manifest.json

ENTRY_NOT_FOUND

Error: Entry module not found: ./dist/graph.js
Code: ENTRY_NOT_FOUND

Cause: The file specified in entry.module doesn’t exist.

Solution:

1. Run npm run build to compile TypeScript
2. Check entry.module path in manifest.json
3. Verify file exists at the specified path

LangChain Errors

TOOL_EXECUTION_FAILED

Error: Tool execution failed

Cause: Gateway returned an error during tool execution.

Solution:

1. Enable debug mode: loadLangChainTriks({ debug: true })
2. Check gateway result for error details
3. Verify input matches expected schema

PASSTHROUGH_CONTENT_NOT_FOUND

Error: Content not found or expired

Cause: Passthrough content reference is invalid or expired.

Solution:

1. Deliver content immediately after receiving ref
2. Don’t store refs for later use
3. Re-execute the action to get fresh content

Registry Errors

RATE_LIMITED

Error: Rate limit exceeded
Code: RATE_LIMITED

Cause: Too many API requests.

Solution:

1. Wait for rate limit reset (check X-RateLimit-Reset header)
2. Reduce request frequency
3. Cache responses locally

FORBIDDEN

Error: You don't have permission to publish this trik
Code: FORBIDDEN

Cause: Trying to publish to a scope you don’t own.

Solution:

1. Use your GitHub username as scope: @yourusername/trik-name
2. Ensure you’re logged in as the correct user

Debugging Tips

Enable Debug Logging

const { tools } = await loadLangChainTriks({
  debug: true
});

Check Full Error

try {
  const result = await gateway.execute(...);
} catch (error) {
  console.error('Full error:', error);
  console.error('Error code:', error.code);
  console.error('Error message:', error.message);
}

Validate Manifest

trik validate ./manifest.json

Test Action Directly

import graph from './graph';
 
const result = await graph.invoke({
  action: 'search',
  input: { topic: 'AI' }
});
 
console.log('Result:', JSON.stringify(result, null, 2));