Antelope
Guides

Troubleshooting

Common errors and their solutions when working with AntelopeJS.

This page covers the most common errors you may encounter when developing with AntelopeJS, along with their causes and solutions.

Interface not implemented

This error occurs in test mode when using stubs. The test runner uses stub mode by default, which rejects calls to interfaces that have no registered implementation.

Your test calls an interface function, but no module provides that interface in the test environment. Stub mode raises this error immediately rather than hanging on an unresolved proxy.

Provide a mock implementation for the interface in your test setup, or use the implement option in your test configuration to wire a real or partial implementation.

Module failed to construct

The construct() function threw an error during the module's initialization phase. Common causes include missing configuration values, unavailable external dependencies, or invalid setup logic.

The core stops the boot sequence when a module fails to construct, because subsequent modules may depend on the interfaces it provides. The error message includes the module ID and the original exception.

Check your module's construct() function and verify the configuration passed via antelope.config.ts. Make sure all required configuration keys are present and that external services (databases, APIs) are reachable before attempting to connect.

Module failed to start

The start() function threw an error. Since start() runs after all modules have been constructed and bindings are resolved, this typically indicates a runtime issue rather than a configuration problem.

The error propagates immediately and prevents subsequent modules from starting. Any modules that depend on interfaces provided by the failed module will not receive those interfaces.

Ensure external services your module depends on are available at start time. If a service may be temporarily unavailable, handle the error internally with try/catch and implement a retry strategy or graceful degradation.

Unresolved interface dependencies

The core validates the interface dependency graph before constructing modules. If a required interface has no provider in the current configuration, the boot fails with this error.

This error means a module declares that it consumes an interface, but no loaded module implements that interface. The core detects this before any construct() call, so the application never partially starts.

Verify that all required modules are listed in antelope.config.ts and that each one implements the expected interfaces. Check for typos in interface package names and ensure the implementing module's package.json includes the correct implements entry.

See also

  • Architecture — How the core handles errors during lifecycle phases
  • Testing — Test configuration and stub mode
  • Configuration — Module configuration reference

Full-Stack Application

Build a complete task management API from scratch using database tables, authentication, and automatic CRUD endpoints in AntelopeJS.

Introduction

Overview of the AntelopeJS CLI — installation, command structure, global options, and configuration storage.