Troubleshooting

Troubleshooting

When your grid bot encounters a problem, it logs specific error messages that tell you exactly what went wrong. This guide covers the most common errors, explains their causes, and provides step-by-step solutions.

BALANCE_CHECK Error

What it means: The bot checked your account balance at startup and found it insufficient for the configured grid.

The check: The bot requires at least order_usd x grid_levels x 1.2 in available balance. The 1.2 multiplier provides a safety margin for fees and price movements. For example, with $100 per level and 20 levels, you need at least $2,400.

Common causes:

• Your account balance is genuinely too low for the configuration.
• Other open positions or orders are consuming margin, reducing available balance.
• You recently changed order_usd or grid_levels without checking your balance.

Solutions:

1. Check your Pacifica DEX account balance.
2. Either deposit more funds to meet the requirement, or reduce your configuration: lower order_usd, reduce grid_levels, or both.
3. Close other positions or cancel other orders that may be using margin.
4. Verify there is no other bot running on the same account consuming balance.

RUNLOCK Error

What it means: The bot tried to acquire its Redis-based run lock and failed. This lock ensures only one bot instance runs per user per symbol.

Common causes:

• Another instance of the same bot is already running. Each user-symbol combination can only have one active bot.
• A previous bot instance crashed without releasing its lock. The lock has a TTL (time-to-live) and will expire automatically, but this takes time.
• Redis is not accessible. The bot requires Redis for the run lock mechanism, and if Redis is down, the bot refuses to start as a safety measure.

Solutions:

1. Check if another bot with the same symbol is running. Stop it first if you want to start a new one.
2. If the previous bot crashed, wait for the lock TTL to expire (typically 2-5 minutes), then try again.
3. Verify Redis is running and accessible. Check your infrastructure configuration.
4. As a last resort, clear the specific lock key in Redis manually, but only if you are certain no other bot instance is running.

Timeout Errors

What it means: An API call to Pacifica DEX did not respond within the expected time.

Common causes:

• Pacifica DEX is experiencing high load or maintenance.
• Your network connection has intermittent issues.
• The exchange rate-limited your requests due to too many API calls.

Impact: The bot handles timeouts gracefully. When a REST snapshot times out, the bot skips that cycle and tries again on the next one. No orders are placed during a cycle with failed data fetching. This prevents the dangerous scenario where missing data is interpreted as “no orders exist.”

Solutions:

1. Check Pacifica DEX status. If the exchange is under maintenance, wait for it to come back.
2. Single timeouts are normal and recover automatically. Only investigate if timeouts persist for more than 5 minutes.
3. Check your cycle_interval_sec setting. If it is very low (under 5 seconds), you may be hitting rate limits. Increase it to 10-15 seconds.
4. Verify your network connection is stable.

WebSocket Disconnection

What it means: The WebSocket connection to the price feed or trade history feed was lost.

Impact: The bot has automatic reconnection logic. Price feed disconnections trigger a fallback to REST API price queries. Trade history disconnections mean fills may be detected later through the periodic REST sync instead of instantly through WebSocket.

Solutions:

1. Usually no action needed. The bot reconnects automatically.
2. If disconnections are frequent (multiple times per hour), check your network stability.
3. Review the logs for any specific error messages accompanying the disconnection.

Bot Starts But No Trades Execute

What it means: The bot is running its cycle but no buy orders are being placed.

Common causes:

• The current price is above all grid levels. The bot only places buy orders below the current price. If the price is above your grid high, no levels qualify.
• All grid levels already have orders or positions. The duplicate prevention system is working correctly.
• The bot is still in its startup phase, performing bootstrap or initial sync.
• The data health guard is blocking order placement due to stale data.

Solutions:

1. Check the current price relative to your grid range. If the price is above your range, no buys will trigger until the price drops.
2. Review the logs for messages about why specific levels were skipped (locked, pending, in-flight, already has position).
3. Wait 2-3 minutes after startup for the initial sync to complete before expecting trades.
4. Check the REST snapshot health in logs to ensure data is fresh.

Grid Break Shutdown

What it means: The price moved outside your grid range for longer than the confirmation period, and the bot performed a clean shutdown.

This is normal behavior, not an error. Grid break protection is a safety feature that prevents the bot from operating in unfavorable conditions.

What to do:

1. Check the current price and your grid range. Understand why the price exited the range.
2. Decide whether to restart with the same range (if you expect the price to return) or reconfigure with an updated range.
3. If grid breaks happen frequently, your range may be too narrow. Consider widening it based on ATR analysis.

Reconciliation Corrections

What it means: The self-healing system detected that expected orders were missing and placed corrective orders.

Occasional corrections are normal. They happen when orders are cancelled by the exchange, rejected silently, or lost during brief connectivity issues. The reconciliation system exists specifically for these situations.

When to worry: If reconciliation corrections happen every few minutes consistently, there may be an underlying issue:

• Check if the exchange is rejecting your orders (insufficient margin, invalid parameters).
• Verify your account does not have restrictions or trading limits.
• Look for error messages in the logs around the time corrections occur.

General Troubleshooting Steps

When you encounter an issue not covered above:

1. Read the logs. The bot logs detailed information about every decision. The answer is almost always in the log output.
2. Check the exchange. Log into Pacifica DEX directly and verify your positions and orders. Compare against what the bot dashboard shows.
3. Stop before changing. If something seems wrong, stop the bot first. The clean shutdown will secure your positions.
4. One change at a time. If you adjust configuration to fix an issue, change one parameter, restart, and observe. Multiple changes make diagnosis impossible.
5. Paper mode test. If you are unsure about a configuration change, test it in paper mode first.

Summary

• BALANCE_CHECK means insufficient funds; either deposit more or reduce order_usd and grid_levels.
• RUNLOCK means another bot instance may be running or a crashed instance left a lock; wait for TTL expiry or verify no duplicate is running.
• Timeout errors are handled automatically; investigate only if they persist beyond 5 minutes.

Next Step

Return to the guide overview to explore more topics or dive into Strategy Guides for advanced configuration techniques.