# Troubleshooting

Common issues when integrating with Fuul and how to resolve them.

{% hint style="warning" %}
Fuul uses a **metadata versioning** system. Any changes to your configuration (conversions, triggers, payout terms) must be **published** from the dashboard for them to go live. If you don't publish, the changes remain in draft and won't process events.
{% endhint %}

## Quick reference

| Symptom                         | Likely cause                                                                      |
| ------------------------------- | --------------------------------------------------------------------------------- |
| Events not appearing            | Configuration not published, wrong event signature, API didn't return `201`       |
| Conversion exists but no payout | Fraud detection flag, user not in audience, payout only set for affiliates        |
| Payout amounts are wrong        | Incorrect payout term configuration, currency mismatch                            |
| Attribution not working         | `sendPageview` or `identifyUser` not called, user didn't arrive via referral link |
| Scheduled events missing        | Token Holder / Subgraph events only log at their scheduled time (0 UTC for daily) |

## Finding conversion events

If you cannot locate a conversion event, follow these steps:

**1. Check the Conversion Logs**

Start by looking in the Conversion Logs section of the dashboard.

<figure><img src="https://785153450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F79eXkwRdaLh40gWqgH2z%2Fuploads%2Fgit-blob-601e5b43a0806316dcb2b86914157701cca7295c%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**2. Search the Event Logs**

If the conversion is not there, go to the **Event Logs** and filter by:

* Date range
* Address or conversion name

<figure><img src="https://785153450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F79eXkwRdaLh40gWqgH2z%2Fuploads%2Fgit-blob-83d0bbd6c973b76375c829750ae6be677924e4e3%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Token Holders and Subgraph events are logged at the scheduled time — at 0 UTC if they run once a day, or at the specific times matching their configured frequency.
{% endhint %}

**3. Event found — check the Trigger Execution**

Open the event and look at the **Trigger Execution** section in the drawer:

| Scenario                                   | Action                                                                        |
| ------------------------------------------ | ----------------------------------------------------------------------------- |
| There's an error                           | Review the error message and adjust the trigger configuration                 |
| Trigger execution exists but no conversion | Check the conversion's **rule configuration** to ensure it's set up correctly |

<figure><img src="https://785153450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F79eXkwRdaLh40gWqgH2z%2Fuploads%2Fgit-blob-878b9733c787dd529812575b94dd8d1bee813b0d%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**4. Event found but no trigger execution**

| Event type       | What to check                                                             |
| ---------------- | ------------------------------------------------------------------------- |
| Off-chain events | Make sure the trigger's **signature** matches the event name sent via API |
| All events       | Check if there are **Condition Filters** set on the trigger               |

**5. Event not in Event Logs**

This means Fuul did not receive the event:

| Event type       | What to check                                                           |
| ---------------- | ----------------------------------------------------------------------- |
| Off-chain events | Verify the API request returned a `201` (created) status                |
| On-chain events  | Verify the trigger configuration — contract address and event signature |

## Finding payouts

If you cannot locate a payout, follow these steps:

**1. Check the Conversion Logs**

Look for the conversion and review its **Payment Status**.

<figure><img src="https://785153450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F79eXkwRdaLh40gWqgH2z%2Fuploads%2Fgit-blob-35c62ef0c032d7d63729df9f5111016682c415e9%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**2. Conversion exists but no payout**

Open the conversion drawer and check the status:

| Possible cause    | Description                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Fraud detection   | The conversion may be flagged as fraud. Fraud only blocks the **referrer** payout — the end user still receives theirs |
| No audience match | The user may not belong to any audience required by the payout rules                                                   |

**3. Check the payout configuration**

If none of the above apply:

* Verify payouts are set correctly — e.g., if payouts are only for affiliates, confirm the conversion involves an affiliate
* Confirm the conversion is configured to generate a payout

<figure><img src="https://785153450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F79eXkwRdaLh40gWqgH2z%2Fuploads%2Fgit-blob-7855d293357e4ed5f52c87ffb228196b916d919a%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**4. Conversion not in logs?**

Follow the steps in **Finding conversion events** above to trace the event.

## Common SDK issues

| Issue                        | Solution                                                                                                                   |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `sendPageview` not tracking  | Ensure `Fuul.init()` is called before `sendPageview`. The SDK must be initialized with a valid API key                     |
| `identifyUser` failing       | Verify the `user_identifier_type` matches the identifier format (`evm_address`, `solana_address`, `xrpl_address`, `email`) |
| Affiliate code already taken | Use `Fuul.isAffiliateCodeAvailable()` to check availability before creating                                                |
| Rewards data not showing     | Rewards are updated hourly — recent conversions and payouts will appear within a maximum of one hour                       |

{% hint style="info" %}
If you've reviewed these steps and still cannot resolve the issue, contact us for assistance.
{% endhint %}