Troubleshooting

This document provides guidance for diagnosing and resolving common issues encountered while using MessageJS. It covers problems ranging from local development environment setup and SDK integration to API authentication and message delivery failures. The information herein is derived directly from the project's source code and documentation.

Troubleshooting is divided into several key areas: initial setup, SDK usage, API request failures, and message processing. Understanding the message lifecycle and the system's error responses is crucial for effective problem-solving. For a complete list of API endpoints and error codes, refer to the API Reference.

Common SDK and Integration Pitfalls

This section addresses frequent issues that arise during the initial setup and integration of the MessageJS client SDK.

• Missing Initialization: The SDK must be initialized with an API key before sendMessage can be called. Failure to do so will result in a client-side error.
• Invalid Phone Number Format: Phone numbers must be in E.164 format (e.g., +1234567890).
• Inactive Connector: Ensure the connector you are trying to use is created and enabled in the MessageJS dashboard.
• Rate Limit Exceeded: High-volume sending may trigger rate limits imposed by your plan or the messaging provider.

Sources: QUICK_START.md:162-169, packages/client/src/index.ts:80-84

API Authentication and Authorization

Authentication issues are a common source of errors. All SDK requests to the /api/v1/messages endpoint must be authenticated using a Bearer token containing a valid API key.

API Key Validation Flow

The validateApiKey middleware intercepts incoming requests to protected routes. It checks for a correctly formatted Authorization: Bearer <api_key> header and validates the key.

The following diagram illustrates the API key validation sequence.

This diagram shows the step-by-step validation performed by the validateApiKey middleware.
Sources: packages/core/src/api/middleware/authMiddleware.ts:16-70

Authentication Error Codes

If authentication fails, the API will respond with a 401 or 403 status code and a specific error code in the JSON body.

Sources: packages/core/src/api/middleware/authMiddleware.ts:22-50, API_REFERENCE.md:323-334

API Request and Resource Errors

Even with successful authentication, requests can fail due to invalid input or issues with associated resources like projects or templates.

Common Validation and Resource Errors

The API validates request bodies and resource existence before processing.

Sources: API_REFERENCE.md:338-356

Message Processing and Status

Understanding the lifecycle of a message is key to diagnosing delivery issues.

Message Lifecycle

When a message is successfully submitted to the API, it is first placed in a queue for processing. Its status is tracked in the database and can be one of several states.

The following flowchart shows the journey of a message from API submission to its final state.

This diagram visualizes the message flow from initial API call to final delivery status update.
Sources: packages/core/src/api/controllers/messageController.ts:25-56, packages/core/prisma/schema.prisma:24-30

Message Statuses

The MessageLog model in the database tracks the status of each message using the MessageStatus enum.

If a message is stuck in QUEUED, it may indicate an issue with the background job processor. A FAILED status will be accompanied by an error message in the MessageLog table, which can help diagnose the root cause (e.g., invalid credentials, third-party API error).

Sources: packages/core/prisma/schema.prisma:24-30

Development Environment

Issues in a local development environment often stem from service connectivity, particularly with the database.

Database Connection

The project uses Docker Compose to run a PostgreSQL database for local development.

# From docker-compose.yml
services:
  postgres:
    image: postgres:15-alpine
    container_name: messagejs_postgres_dev
    environment:
      POSTGRES_USER: messagejs
      POSTGRES_PASSWORD: password
      POSTGRES_DB: messagejs_dev
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: always

Sources: docker-compose.yml:13-32

To troubleshoot database issues:

1. Ensure Docker is running: The Docker daemon must be active.
2. Start the container: Run docker-compose up -d from the project root.
3. Check container status: Run docker ps and ensure the messagejs_postgres_dev container is running and port 5432 is mapped.
4. Verify environment variables: The DATABASE_URL in your packages/core/.env file must match the credentials in docker-compose.yml. The expected format is postgresql://messagejs:password@localhost:5432/messagejs_dev.

The following diagram shows the local service architecture.

This diagram illustrates the connection between the Node.js application and the Dockerized PostgreSQL database.
Sources: docker-compose.yml, packages/core/src/index.ts:16