Troubleshooting Guide

Use this page when “something just isn’t working.”

Issues fall into four broad buckets: Install, Connectivity, Message Routing, and Runtime Health. Each section lists the most common symptoms and quickest fixes.

Installation Issues

Symptom | Where to Look / What to Do

Installer.exe install exits with an error text | Open the generated log in C:\abs\logs\*.install.log. Search for ERROR lines—most failures are missing parameters ($CENTRALHOSTNAME) or a bad PowerShell execution policy.

Containers never appear after reboot | Run Installer.exe install again—first run only enabled Windows features and requested a restart.

Cannot find docker-compose.yml | Components unpack into C:\abs\config; make sure SystemConfig.json points at the correct Windows version (2022.zip).

Connectivity & Auth

Symptom | Likely Cause / Resolution

ACCESS_REFUSED - Login was refused in Drex | Wrong username/password. Double-check adapter credentials or regenerate via Installer.exe configure-rabbit.

Shovel stuck in Starting state | • Central DNS/port unreachable • Certificate expired or missing • Site not registered on Central (vessels folder).

Central UI (https://…:15671) shows invalid certificate | New cert issued but RabbitMQ container not restarted. Run docker restart rabbitmq-central.

Site Drex log shows bad tenant | Missing or incorrect tenant headers; ensure adapter sets either x.abs.ten.cc.id or the client-tenant pair.

Message Routing Problems

Symptom / Log Line | Root Cause / Fix

Message lands in q.cc.drex.router.feedback.dl | Required header missing (target app/site). Inspect headers in RabbitMQ UI, then add the field in adapter code.

Feedback queue returns BAD_APP | TargetApp.Name not registered at the target site. Add adapter JSON on that site or correct the name.

Broadcast doesn’t reach any adapters | x.abs.scope not set to BROADCAST, or Broadcast.Topics in adapter registration missing the topic.

Direct message never consumed | Destination adapter disabled Direct.Enable or queue auto-deleted. Re-enable and save the adapter file.

Runtime & Performance

Symptom | Diagnostic Steps / Remedy

DREX-M container in continuous restart loop | docker logs <container> – look for JSON parse errors or missing env-vars. Fix the offending file; Drex auto-restarts itself after crash.

High message latency | docker stats – check CPU of RabbitMQ. Increase PrefetchCountIncoming / Outcoming in appsettings.json and let Drex auto-restart.

Queues grow without being consumed | Consumer app offline or acking incorrectly. Tail adapter logs; ensure BasicAck/AcknowledgeAsync is called.

Shovel queue length keeps climbing | WAN outage or Central unavailable. Drex will auto-retry; verify network and Central health.

Useful Commands

# List containers and health status

docker ps

Example output:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES

bbf6eed0d6b2 drex-message-service "dotnet Abs.CommonCo…" 30 hours ago Up 30 hours (healthy) 0.0.0.0:12345->5000/tcp drex-message-service

Status column expected to show healthy.

In most cases container logs will capture the problem. Use container name or id from the docker ps command output.

# Tail logs for a specific container

docker logs -f <container name>

# View the 100 most recent Drex log lines

docker logs <container name> --tail 100

# Check shovel status inside RabbitMQ (Site -> Central)

docker exec -it rabbitmq-vessel C:/rabbitmq/sbin/rabbitmqctl.bat shovel_status

# Check shovel status inside RabbitMQ (Central -> Cloud)

docker exec -it rabbitmq-central C:/rabbitmq/sbin/rabbitmqctl.bat shovel_status

Example output:

Shovel status on node rabbit@rabbitmq-vessel

name type state source vhost destination termination_reason destination_protocol source_protocol last_changed source_queue destination_exchange

central.feedback.incoming dynamic running amqps://rabbitmq-central:5671/commoncore commoncore amqp://rabbitmq-vessel:5672/commoncore amqp091 amqp091 2025-08-07 10:56:49 q.cc.drex.vessel.outbox.feedback.1488 e.cc.drex.portal.feedback

central.feedback.outgoing dynamic running amqp://rabbitmq-vessel:5672/commoncore commoncore amqps://rabbitmq-central:5671/commoncore amqp091 amqp091 2025-08-07 10:56:50 q.cc.drex.outbox.feedback e.cc.drex.portal.feedback

central.incoming dynamic running amqps://rabbitmq-central:5671/commoncore commoncore amqp://rabbitmq-vessel:5672/commoncore amqp091 amqp091 2025-08-07 10:56:50 q.cc.drex.vessel.outbox.1488 e.cc.drex.portal

central.outgoing dynamic running amqp://rabbitmq-vessel:5672/commoncore commoncore amqps://rabbitmq-central:5671/commoncore amqp091 amqp091 2025-08-07 10:56:50 q.cc.drex.outbox e.cc.drex.portal