Key Considerations & Common Pitfalls

Because Fluxify runs your custom scripts on the server, writing improper code can cause workflow execution failures, return 500 Internal Server Error statuses to clients, or degrade server-wide performance.

Pay close attention to the following constraints and pitfalls when scripting.

1. Global Variable Mutation (Context Corruption)

Every block in a workflow execution shares the same mutable context object. Any global helper variables (like setHeader, logger, jwt, getConfig, etc.) are injected as properties into this context.

CAUTION

Overwriting or deleting these built-in globals will corrupt the environment for the current run.

For example, running setHeader = null; or delete jwt; in a script will make that helper unavailable. Any subsequent block or expression in the workflow attempting to use it will throw a TypeError: setHeader is not a function, instantly halting the workflow and returning a 500 Internal Server Error to the caller.

Best Practice

• Treat all built-in global functions and objects as read-only.
• Avoid assigning values to variables without declaring them (const, let, var), as this writes them to the shared global scope.
• Never use variable names that shadow built-in globals:

  // ❌ BAD: Shadows the built-in HTTP request helper
  const getHeader = "my-header"; 
  
  // ❌ BAD: Destroys the built-in logger reference for subsequent blocks
  logger = null;

2. Missing return Statements

All user scripts are implicitly wrapped in an async function, which is why await always works and why a result must be returned.

WARNING

If your script does not explicitly use a return statement, it will return undefined.

Downstream blocks often expect the output of a JS Runner or Transformer block to be a JSON object or string. If your script returns undefined, subsequent blocks trying to read properties (e.g. input.data) will throw a runtime error like TypeError: Cannot read properties of undefined, causing the workflow to fail with a 500 error.

Best Practice

• Always return a value, even if it is just a success status or empty object:

  // Always return something
  return { success: true };

3. Unresolved Async Promises (Resource Leaks)

Fluxify supports async/await.

IMPORTANT

Route timeouts are optional and controlled by the experimental experimental.workerTimeouts.enabled project setting. When enabled, the entire route has a 30-second timeout by default (or its configured per-route timeout). A stalled worker that exceeds that limit can be terminated by the supervisor.

Even with that guard enabled, unresolved database connections, infinite fetch loops, or un-ending timers can consume server resources. Ensure asynchronous work has a clear completion path.

Best Practice

• Always specify timeouts on external fetches or operations (e.g., using Axios timeouts in httpClient).
• Ensure all promises resolve or reject under all circumstances.

4. Unhandled Runtime Exceptions

Executing operations on unverified inputs (like calling a method on null or undefined) throws runtime exceptions.

// ❌ RISKY: If input.user is null, this throws "Cannot read properties of null (reading 'email')"
return input.user.email;

If an unhandled exception is thrown inside a script:

• The execution engine terminates the workflow immediately.
• If no Error Handler Block is configured, the server returns a 500 Internal Server Error status containing the raw stack trace.

Best Practice

• Always sanitize and validate input variables using Zod or standard null-checks:

  // Option A: Optional chaining
  return input?.user?.email || null;
  
  // Option B: Standard validation
  if (!input || !input.user) {
    logger.logWarn("User not found in input");
    return null;
  }
  return input.user.email;

• Always configure an Error Handler Block in your workflow to catch script failures and return client-friendly JSON responses instead of 500 errors.

5. Memory Exhaustion

Scripts run in-process on the server. If a script allocates massive structures (e.g. loading a 100MB database result, or infinite loops appending to a string), it can exhaust process memory. This will cause the garbage collector to consume 100% CPU or trigger an Out-Of-Memory (OOM) crash of the entire server instance, knocking out all API routes.

Best Practice

• Never process massive datasets inside workflow script blocks. Use paginated queries or external database transformations.
• Avoid nesting loops that allocate memory dynamically.