Common Issues

This page covers the most frequently encountered issues when deploying Fystack, along with solutions.

CORS and CSRF Errors

Symptom: After signing in, you see errors in the browser console like:

• Access to XMLHttpRequest has been blocked by CORS policy
• CSRF token mismatch
• Authentication cookies not being set
• Sign-in appears to work but you're immediately logged out

Root cause: The API's CORS configuration doesn't match where the frontend is being served from, or cookie settings prevent the browser from storing authentication tokens.

Solution

Check these settings in ./dev/config.yaml:

# 1. CORS must match your frontend URL exactly (including protocol)
cors:
  allow_origins: https://app.yourdomain.com  # NOT http://, NOT a different domain

# 2. Cookie same_site must be appropriate
cookie:
  same_site: strict  # Works for localhost and subdomain setups (app.domain.com + api.domain.com)

# 3. App URLs must use the correct protocol
app:
  root_url: https://app.yourdomain.com  # Must match cors.allow_origins

After making changes, recreate Apex to pick up the new config:

docker compose -f ./dev/docker-compose.yaml up -d --force-recreate apex

Common Mistakes

Mistake	Fix
cors.allow_origins uses http:// but site uses HTTPS	Change to https://
cors.allow_origins has a trailing slash	Remove trailing slash
cookie.same_site: none without HTTPS	Set up HTTPS first, or use strict if on same domain/subdomains
Frontend and API on different root domains with strict	Change to none (requires HTTPS)
API_BASE_URL uses http:// but nginx serves HTTPS	Update to https://

Docker Login / Image Pull Errors

Symptom: docker compose up fails with "image not found" or "unauthorized" errors.

Root cause: You're not authenticated with Docker Hub, or the credentials are incorrect.

Solution

docker login -u fystacklabs
# Enter the password when prompted

# Verify by pulling an image
docker pull fystacklabs/apex:1.0.45

If you don't have credentials, join the Fystack Telegram community.

Port Conflicts

Symptom: docker compose up fails with "port already in use" errors.

Root cause: Another service on your system is using the same port.

Solution

Check which process is using the port:

sudo lsof -i :8150  # or whatever port is conflicting

Either stop the conflicting service or modify the port mapping in docker-compose.yaml:

# Change the host port (left side) only
ports:
  - "127.0.0.1:9150:8150"  # Changed from 8150 to 9150 on the host

warning

If you change the Apex port, update API_BASE_URL accordingly and recreate the UI container.

Consul ACL Permission Denied

Symptom: Logs show errors like:

rpc error: code = Unknown desc = Permission denied: token with AccessorID '...' lacks permission 'key:write'

Root cause: When using an external Consul instance (e.g., Kubernetes Helm chart) with ACLs enabled, the Apex service doesn't have write permissions.

Solution

The default Docker Compose Consul runs without ACLs, so this only affects custom deployments. If using external Consul with ACLs:

1. Create a Consul policy that allows key:write for the Fystack prefix
2. Create a token with that policy
3. Add the token to config.yaml:

consul:
  address: "your-consul-address:8500"
  token: "your-consul-token"

And in config.indexer.yaml:

services:
  kvstore:
    consul:
      token: "your-consul-token"

Pending Blocks / Indexer Stuck

Symptom: Transactions aren't being detected, or the indexer logs show it's stuck at a certain block number.

Root cause: Usually caused by rate-limited public RPC endpoints or network connectivity issues.

Solution

1. Check indexer logs:

docker compose -f ./dev/docker-compose.yaml logs -f multichain-indexer

2. Use a paid RPC provider instead of public endpoints. Public RPCs have rate limits that cause pending blocks. Recommended providers:

   • Alchemy
   • Infura
   • QuickNode

3. Reset block state if the indexer is stuck. Block state is stored in Consul KV or Redis:

# Check current block state in Consul
curl http://127.0.0.1:8501/v1/kv/?keys | jq .

# Delete stuck state (use with caution)
curl -X DELETE http://127.0.0.1:8501/v1/kv/block_state/CHAIN_KEY

4. Update RPC endpoints in config.yaml and config.indexer.yaml:

# config.yaml
networks:
  ETHER_SEPOLIA_TESTNET:
    providers:
      - name: "alchemy"
        http: "https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY"
        wss: "wss://eth-sepolia.g.alchemy.com/v2/YOUR_KEY"

# config.indexer.yaml
chains:
  eth_sepolia:
    nodes:
      - url: "https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY"

MPC Nodes Not Starting

Symptom: mpcium-node0, mpcium-node1, or mpcium-node2 containers exit immediately after starting.

Solution

1. Check logs:

docker compose -f ./dev/docker-compose.yaml logs mpcium-node0

2. Verify node configs exist:

ls -la ./dev/node-configs/node0/
# Should contain: config.yaml, peers.json, identity/

3. Re-run setup if configs are missing:

./fystack-ignite.sh

Database Migration Failures

Symptom: The migrate container exits with a non-zero code, and Apex doesn't start.

Solution

1. Check migration logs:

docker compose -f ./dev/docker-compose.yaml logs migrate

2. Verify PostgreSQL is healthy:

docker compose -f ./dev/docker-compose.yaml ps postgres

3. Retry migrations:

docker compose -f ./dev/docker-compose.yaml up -d migrate

CoinMarketCap API Errors

Symptom: Price data is not loading, or logs show CoinMarketCap API errors.

Solution

Verify your API key is set in config.yaml:

price_providers:
  coinmarketcap:
    api_key: "your-key-here"  # Must not be empty

Check that the key is valid:

curl -H "X-CMC_PRO_API_KEY: your-key-here" \
  "https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest?symbol=BTC"

Getting Help

If your issue isn't covered here:

1. Check the Fystack GitHub for known issues
2. Join the Fystack Telegram community for support