TrikHub
TrikHub/Docs

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
  1. Load the trik: await gateway.loadTrik('./path/to/trik')

INVALID_INPUT

Error: Invalid input for tool 'searchArticles'
Code: INVALID_INPUT

Cause: Input doesn’t match the tool’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.executeExposedTool(
  'demo/article-search',
  'searchArticles',
  { topic: 'AI' }  // Correct
  // { topic: 123 }  // Wrong: number instead of string
);

INVALID_OUTPUT

Error: Tool "searchArticles" returned invalid output
Code: INVALID_OUTPUT

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

Solution:

  1. Check your tool handler returns correct structure
  2. Verify output matches outputSchema (tool mode) or logSchema (conversational mode)
  3. Ensure all declared properties are present with correct types

EXECUTION_TIMEOUT

Error: Trik execution timed out
Code: EXECUTION_TIMEOUT

Cause: Trik exceeded maxTurnTimeMs.

Solution:

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

HANDOFF_IN_PROGRESS

Error: A handoff is already active
Code: HANDOFF_IN_PROGRESS

Cause: Attempted to start a new handoff while one is already active.

Solution:

  1. Complete the current handoff first (trik calls transfer_back)
  2. Force transfer-back with /back command
  3. Use gateway.getActiveHandoff() to check the current state before starting a new handoff

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: schemaVersion, id, name, version, agent, entry
  2. Check JSON syntax
  3. Run trik lint .

ENTRY_NOT_FOUND

Error: Entry module not found: ./dist/index.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

Linter Errors

tdps-agent-safe-output

⚠ [tdps-agent-safe-output] outputSchema property "summary" uses an unconstrained string

Cause: A string property in outputSchema has no constraint (enum, format, or pattern). maxLength alone is not agent-safe.

Solution: Add enum, format, or pattern to the property, or use conversational mode with logSchema for free-text content.

tdps-constrained-log

⚠ [tdps-constrained-log] logSchema property "query" is an unconstrained string

Cause: A string property in logSchema has no constraint (enum, format, pattern, or maxLength).

Solution: Add at least one constraint. For logSchema, maxLength is acceptable.

tdps-log-template

⚠ [tdps-log-template] logTemplate placeholder "{{xyz}}" not found in logSchema

Cause: A {{placeholder}} in logTemplate doesn’t match any property in logSchema.

Solution: Add the missing property to logSchema or fix the placeholder name.

tdps-output-template

⚠ [tdps-output-template] outputTemplate placeholder "{{xyz}}" not found in outputSchema

Cause: A {{placeholder}} in outputTemplate doesn’t match any property in outputSchema.

Solution: Add the missing property to outputSchema or fix the placeholder name.

LangChain Errors

TOOL_EXECUTION_FAILED

Error: Tool execution failed

Cause: Gateway returned an error during tool execution.

Solution:

  1. Enable debug mode when loading triks
  2. Check gateway result for error details
  3. Verify input matches expected schema

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

import { loadLangChainTriks } from '@trikhub/langchain';
 
const { tools } = await loadLangChainTriks({
  debug: true
});

Check Full Error

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

Validate Manifest

trik lint .

Check Handoff State

const activeHandoff = gateway.getActiveHandoff();
console.log('Active handoff:', activeHandoff);
// { trikId: "article-search", sessionId: "...", turnCount: 3 } or null

Test Tool Execution Directly

// For tool-mode triks
const output = await gateway.executeExposedTool(
  'my-trik',
  'searchArticles',
  { topic: 'AI' }
);
console.log('Output:', output);