Troubleshooting Common Issues

"License expired"

What it means: Your license has expired or IkaSolver can't verify it.

Solutions:

1. Connect to the internet. IkaSolver needs to contact the license server periodically. If you've been offline, simply reconnecting will resolve this.
2. Grace period. There's a 3-day grace period after the last successful verification. During this time, a dismissable warning banner appears showing how many hours remain: "License expired. Connect to the internet to verify - Xh remaining in grace period." The app remains functional during the grace period.
3. Renew your license at your dashboard if the subscription has genuinely expired.

"Device limit reached"

What it means: You've activated IkaSolver on the maximum number of devices allowed by your license plan and are trying to activate on a new one.

Solutions:

1. Deactivate an old device. In IkaSolver, go to Settings > License > Remove License. A confirmation dialog warns that this can only be done once every 30 days. Alternatively, deactivate from the web dashboard at your dashboard.
2. After deactivating the old device, activate your license on the new device.

"Device transfer cooldown"

What it means: You recently deactivated a device and are trying to activate on a new one, but the 30-day cooldown hasn't elapsed yet.

What to do: The error message shows the exact date when you can add a new device: "Device transfer cooldown active. You can add a new device after YYYY-MM-DD." You need to wait until that date.

"Invalid license key"

What it means: The license key you entered doesn't match any valid license.

Solutions:

1. Double-check the key for typos - copy and paste it directly from your purchase confirmation email.
2. Make sure you're using the correct key for your license tier.

"This license has been revoked"

What it means: The license has been permanently disabled by the administrator.

What to do: Contact support if you believe this is an error.

High RAM Usage

Large trees can require significant memory. If you're running out of RAM or the solver crashes:

1. Check the RAM estimate first. Open Settings > Memory > Estimate RAM before starting a solve. This gives you an accurate prediction of how much memory the solve will need.
2. Reduce abstraction buckets. Lower the flop, turn, and river bucket counts in Settings > Abstraction. The default of 30 buckets per street is a good balance, but you can go lower (e.g., 15-20) for larger trees. Fewer buckets means less RAM but slightly lower accuracy.
3. Use flop subsets. In Settings > Abstraction, change the flop texture from "Perfect (1755)" to a subset option like "Subset (487)" or "Subset (198)". Subsets sample a weighted subset of canonical flops, dramatically reducing memory while retaining good preflop convergence.
4. Reduce texture quality. Set turn and river textures to "Small" or "None" instead of "Large" or "Perfect".
5. Lower the "Keep EV" / "Keep Avg" streets. In Settings > General, reducing these values stores less auxiliary data per street. The default Keep EV of 1 is already minimal; Keep Avg at 4 stores average strategies for all streets - lowering this saves memory.
6. Use a remote solver. Offload the solve to a server with more RAM. See remote solver setup.
7. Simplify the tree. Use fewer bet sizes or fewer players. Each additional bet size option multiplies the tree size. See bet sizing.

Slow Convergence

If the solver is taking too long to reach acceptable volatility:

1. Add more threads. Open Settings > General > Threads and increase the thread count. The solver scales well across cores - using all available CPU cores is recommended. You can change thread count while the solver is running.
2. Enable size optimization. This feature finds the optimal single raise size per node on the starting street, which can significantly accelerate convergence by pruning suboptimal sizes.
3. Use the "Balanced" abstraction preset. In Settings > Abstraction, the "Balanced" mode uses tested defaults (Subset-487 flop texture, small turn/river textures) that converge faster than "Perfect" settings with minimal accuracy loss.
4. Lower abstraction complexity. Reducing bucket counts speeds up each iteration. The solver does more work per iteration with more buckets.
5. Use iterations per node. Instead of a flat iteration count, set Per node in Settings > General. This scales total iterations to the tree's complexity, ensuring smaller trees don't over-iterate and larger trees get enough passes.
6. Check target volatility. If you've set a target volatility in Settings, the solver stops when it reaches that threshold. Make sure it's not set unrealistically low (e.g., 0.0001), which may never be achieved.

Connection Refused

Symptoms: "Connection refused" or timeout when trying to connect.

Solutions:

1. Verify the server is running. Check that ikasolver --serve is active on the server and showing "Listening on 0.0.0.0:PORT".
2. Check the port. Make sure the port in the GUI matches what the server is using (default 9876).
3. Check the IP address. Use the server's correct network-reachable IP. If you're on the same local network, use the local IP (e.g., 192.168.x.x). For remote servers, use the public IP.
4. Firewall. Make sure the port is open in the server's firewall. On Linux: sudo ufw allow 9876/tcp or the equivalent for your firewall.
5. Network routing. If connecting across the internet, ensure port forwarding is configured on the server's router, or use a VPN/SSH tunnel.

Authentication Failed

Symptoms: Connection is established but immediately rejected with an auth error.

Solutions:

1. Check the token. The token in the GUI must exactly match what the server is using. Copy it directly from the server's console output.
2. Whitespace. Make sure there's no leading or trailing whitespace in the token field.

Remote Solver Disconnects

Symptoms: The green connection dot disappears, error banner shows "Remote server disconnected."

Solutions:

1. Check the server. SSH into the server and verify ikasolver --serve is still running. It may have crashed due to an out-of-memory condition.
2. Network stability. Unstable Wi-Fi or internet can drop the WebSocket connection. The GUI checks for connectivity every 2 seconds and detects disconnects quickly.
3. Server-side errors. Check the server console for error messages. Common issues include running out of memory during a solve.
4. Reconnect. The solver state is preserved on the server - simply click Connect again in Settings. If the solve was running, it continues where it left off.

Solver Starts but Shows No Progress

Possible causes:

1. Tree not built. Make sure you've built the tree (TREE tab > Build) before starting the solver. The solver needs a built tree to work with.
2. Zero iterations. Check that the iteration count in Settings isn't set to 0 (which means unlimited) with a target volatility that's already satisfied.

"Tree is required" Error (CLI)

When running from the command line, the --tree flag is required unless you're using --serve mode:

ikasolver --tree game.tree -j 8 -i 100000

App Feels Slow or Unresponsive

1. Adjust UI scale. In Settings > Display, reduce the UI Scale if the app is rendering too many pixels.
2. Close other applications. If the solver is using most of your RAM, the OS may be swapping, which slows everything down.
3. Reduce polling. During a large solve, the GUI polls for stats updates. If browsing results feels sluggish while the solver is running, try pausing the solve to free up CPU.