Skip to content
Prividium

Developer Troubleshooting

This page lists common errors and how to resolve them. For SDK and RPC patterns, see Building Web Applications.

Quick diagnosis

Run the following command to automatically check your Prividium configuration, API connectivity, and authentication setup from the command line:

npx prividium doctor -r {{PRIVIDIUM_API_URL}} -u {{USER_PANEL_URL}}

The -r flag points to the Prividium API and -u to the user panel URL used for browser-based authentication. The doctor command validates connectivity, OIDC settings, and network reachability, and reports any issues it finds.

Verify user and configuration

Call GET /api/profiles/me with a valid session (Bearer token) to confirm the authenticated user's identity, assigned roles, and linked wallets. Mismatched roles or missing wallet associations cause many access-denied or transaction-not-authorized issues. Use this as a sanity check before debugging permissions.

troubleshooting.ts
    const response = await fetch(`${PRIVIDIUM_API_URL}/api/profiles/me`, {
        method: 'GET',
        headers: { Authorization: `Bearer ${token}` }
    });
    if (!response.ok) throw new Error(`Profile request failed: ${response.status}`);
    const profile = await response.json();
    // Check profile.roles and profile.wallets

RPC -32001 Forbidden or access denied to a function

The RPC returns HTTP 200 with error.code -32001 when the user is authenticated but not allowed to call that contract or method. See RPC Error Codes for the full code reference.

Best practice: Have an administrator check Contract Permissions: (1) Contract is registered and the function is listed. (2) Function permission level is not Forbidden and matches the intended access (All Users, Check Role, or Restrict Argument). (3) If Check Role is used, the user has one of the allowed roles (check Users in the Admin Dashboard).

401 Unauthorized

Missing or invalid session or token. Use the authenticated transport for reads and ensure the token is sent with requests. For causes and fix with code examples, see Building Web Applications – Error Handling.

Transaction not authorized or wallet errors

Transaction authorizations are required for write operations via the Per-User RPC. Call authorizeTransaction before sending; ensure the wallet address is linked to the user in the Admin Panel. Errors like "User is not authorized to perform this action" or "Wallet address is not associated with the user" mean the authorization check or user–wallet link failed. See Per-User RPC for transaction authorization lifecycle and Building Web Applications – Error Handling for the 401-on-write and pre-fetch pattern.

Other common errors