---

name: dojo-debug description: | Use when debugging and troubleshooting dojo.js applications. Triggers: dojo error, torii connection, entity not found, type mismatch, debug dojo, troubleshoot, subscription error, sync issues

Dojo.js Debugging & Troubleshooting

When to Use

Use this skill when:

• Debugging connection issues
• Troubleshooting entity sync problems
• Fixing type mismatches
• Diagnosing subscription errors

Connection Issues

Torii Not Responding

Copy# Check if Torii is running
curl http://localhost:8080/health

# Check Torii logs
katana & torii --world 0x... --rpc http://localhost:5050

Common causes:

• Torii not started
• Wrong toriiUrl in config
• CORS blocking requests
• World address mismatch

CORS Errors

CopyAccess to fetch blocked by CORS policy

Solution: Start Torii with CORS enabled:

Copytorii --world 0x... --allowed-origins "*"

WebSocket Connection Failed

Copy// Check if WebSocket is supported
if (typeof WebSocket === 'undefined') {
    console.error("WebSocket not available");
}

// Try gRPC instead
import { initGrpc } from "@dojoengine/sdk";
const grpcClient = await initGrpc({ toriiUrl, worldAddress });

Entity Issues

Entity Not Found

Copy// Debug: Check if entity exists
const { useDojoStore } = useDojoSDK();
const allEntities = useDojoStore.getState().entities;
console.log("All entities:", Object.keys(allEntities));

// Verify entity ID format
import { getEntityIdFromKeys } from "@dojoengine/utils";
const entityId = getEntityIdFromKeys([BigInt(key1), BigInt(key2)]);
console.log("Expected entityId:", entityId);

Common causes:

• Wrong entity key(s)
• Entity not yet indexed by Torii
• Query filter too restrictive

Entity Not Updating

Copy// Check subscription is active
const [data, subscription] = await sdk.subscribeEntityQuery({...});
console.log("Subscription active:", subscription);

// Verify callback is being called
callback: ({ data, error }) => {
    console.log("Callback triggered:", { data, error });
}

Common causes:

• Subscription filter doesn't match entity
• Callback throwing error
• Store not being updated

Type Issues

Schema Type Mismatch

CopyType 'X' is not assignable to type 'Y'

Solution: Regenerate types from ABI:

Copynpx @dojoengine/core compile-abi path/to/manifest.json

Model Name Format

Copy// Wrong
useModel(entityId, "Player");       // Missing namespace
useModel(entityId, "game_Player");  // Wrong separator

// Correct
useModel(entityId, "game-Player");  // namespace-ModelName

Subscription Errors

Subscription Callback Error

Copy// Wrap callback in try-catch
callback: ({ data, error }) => {
    try {
        if (error) {
            console.error("Subscription error:", error);
            return;
        }
        processData(data);
    } catch (e) {
        console.error("Callback error:", e);
    }
}

Memory Leaks

Copy// Always cleanup subscriptions
useEffect(() => {
    let subscription;

    async function setup() {
        [, subscription] = await sdk.subscribeEntityQuery({...});
    }
    setup();

    return () => {
        if (subscription) {
            subscription.cancel();
        }
    };
}, []);

Transaction Errors

Insufficient Funds

CopyTransaction reverted: insufficient balance

Solution: Fund the account:

Copy// Check balance
const balance = await provider.provider.getBalance(account.address);
console.log("Balance:", balance);

Nonce Mismatch

CopyInvalid transaction nonce

Solution: Wait for pending transactions:

Copyawait account.waitForTransaction(tx.transaction_hash);

Contract Not Found

CopyContract not found in manifest

Solution: Verify contract name and namespace:

Copyconsole.log("Manifest contracts:", manifest.contracts.map(c => c.tag));

Performance Issues

Slow Queries

Copy// Use pagination
const query = new ToriiQueryBuilder()
    .withLimit(50)  // Smaller batches
    .addEntityModel("game-Player")  // Specific models only
    .build();

// Consider gRPC for better performance
import { initGrpc } from "@dojoengine/sdk";

Too Many Re-renders

Copy// Use selectors to minimize updates
const score = useDojoStore(
    state => state.entities[entityId]?.models?.game?.Player?.score,
    (a, b) => a === b  // Custom equality
);

// Use memo for expensive computations
const sortedPlayers = useMemo(() =>
    Object.values(entities).sort((a, b) => b.score - a.score),
    [entities]
);

Debugging Tools

Log All Store Changes

CopyuseDojoStore.subscribe((state, prevState) => {
    console.log("Store changed:", {
        added: Object.keys(state.entities).filter(k => !prevState.entities[k]),
        removed: Object.keys(prevState.entities).filter(k => !state.entities[k])
    });
});

Query Torii Directly

Copy# Check indexed entities
curl "http://localhost:8080/entities?model=game-Player&limit=10"

# Check events
curl "http://localhost:8080/events?limit=10"

Enable SDK Logging

Copyconst provider = new DojoProvider(manifest, rpcUrl, "debug");

Common Error Messages

Quick Diagnostics

Copy// Add to your app for debugging
function DebugPanel() {
    const { sdk, config, useDojoStore } = useDojoSDK();
    const entityCount = useDojoStore(s => Object.keys(s.entities).length);

    return (
        <div style={{ position: 'fixed', bottom: 0, right: 0, background: '#000', color: '#0f0', padding: 10 }}>
            <div>Torii: {config.toriiUrl}</div>
            <div>World: {config.manifest?.world?.address?.slice(0, 10)}...</div>
            <div>Entities: {entityCount}</div>
        </div>
    );
}