Error Handling

Errors thrown inside an Aktor propagate up through the Aktor graph. The Reaktor catches them, records the failure in the execution log, and surfaces the error in the Reaktor-Trace. This page covers two patterns: graph-traversal guards and error handling inside AktorFunctions.

Graph Traversal Guards

The Aktor framework performs an initial "dry run" during graph construction to determine the execution tree. During this traversal, Aktor parameters have their Zod default values — empty strings, zeros, and undefined. If your Aktor function calls an external API or performs side effects, this dry run would trigger them with empty inputs.

Guard against this by returning early when parameters are empty:

import { createAktorFunction } from '@operaide/aktor';

const aktorSearchDocuments = createAktorFunction('aktorSearchDocuments',
    async ({ query, database }: { query: string; database: string }) => {
        if (!query) return { results: [] };  // Guard: skip during graph traversal
        // ... actual search logic
        return { results: await db.search(query) };
    }
);

This pattern is especially important for:

• LLM tool functions created with aktorToTool — the LLM parameters (parameters) are empty during traversal
• Database operations — avoid inserting empty rows
• HTTP calls — avoid sending requests with empty payloads

Error Handling in AktorFunctions

Catch recoverable errors inside the function, re-throw unrecoverable ones with a clear message so they appear meaningfully in the Reaktor-Trace.

import { createAktorFunction } from '@operaide/aktor';
import axios from 'axios';

const aktorCallExternalAPI = createAktorFunction('aktorCallExternalAPI',
    async ({ url }: { url: string }) => {
        if (!url) return null;  // Graph traversal guard

        try {
            const response = await axios.get(url);
            return response.data;
        } catch (error) {
            if (axios.isAxiosError(error)) {
                const status = error.response?.status;
                throw new Error(`API call failed: ${status ?? error.message}`);
            }
            throw error;  // Re-throw unknown errors
        }
    }
);