> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roll.codes/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve the most common roll.codes integration failures, including install issues, callback authorization problems, and stuck requests.

Use this page when the starter flow or your own consumer integration does not behave as expected.

## Build fails due remapping errors

### Symptom

Imports like `@rollcodes/...` cannot be resolved.

### Fix

```txt theme={null}
@rollcodes/=lib/roll.codes/src/
forge-std/=lib/forge-std/src/
```

Then re-run:

```bash theme={null}
forge build --zksync
```

## `forge install` fails

### Symptom

Dependency installation fails while cloning or resolving the target repo.

### Fix

```bash theme={null}
forge install roll.codes=jarrodwatts/roll.codes@main --no-git
forge install forge-std=foundry-rs/forge-std --no-git
```

If `main` is unavailable, pin a known tag or commit with `--git-ref`.

## `Unauthorized` during callback

### Symptom

`randomNumberCallback` reverts with an authorization error.

### Cause

The callback caller is not the configured coordinator.

### Fix

* enforce `msg.sender == address(vrfSystem)`
* confirm the deployed coordinator address matches the target network
* verify the callback is pointing at the expected contract

## `IncorrectFee` or request revert

### Symptom

The request call reverts before creating a valid request.

### Cause

`msg.value` does not match `requestFee()`.

### Fix

```solidity theme={null}
uint256 fee = vrfSystem.requestFee();
vrfSystem.requestRandomNumberWithTraceId{value: fee}(traceId);
```

roll.codes requires the exact fee in `msg.value` for this request flow.

## Requests stay pending

### Symptom

You see the request transaction, but no fulfillment callback arrives.

### Check

* confirm the request event was emitted on-chain
* confirm the coordinator address is correct
* confirm your callback does not revert
* if you run your own infrastructure, verify relayer and signer setup

## Where to go next

<CardGroup cols={2}>
  <Card title="Integration pattern" icon="blocks" href="/contracts/integration-pattern">
    Recheck the minimal request and callback flow.
  </Card>

  <Card title="Callback security" icon="shield-check" href="/concepts/callback-security">
    Validate the required callback guards.
  </Card>

  <Card title="Coordinator reference" icon="file-text" href="/contracts/coordinator-reference">
    Confirm the request function, `requestFee()` usage, and callback interface.
  </Card>
</CardGroup>