> For the complete documentation index, see [llms.txt](https://docs.zeroauthority.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zeroauthority.xyz/nova-bot/token-gated-discord-roles/faq-and-troubleshooting.md).

# FAQ & Troubleshooting

[#roles-were-not-assigned-why](#roles-were-not-assigned-why "mention")<br>

[#sync-ran-but-roles-didnt-change-why](#sync-ran-but-roles-didnt-change-why "mention")

[#setup-failed-why](#setup-failed-why "mention")

[#security-and-trust](#security-and-trust "mention")

[#still-stuck](#still-stuck "mention")

### Roles were not assigned — why?

#### 1️⃣ The bot’s role is below the gated role

**What this means**

Discord does **not** allow a bot to assign roles that are higher than (or equal to) its own highest role.

**How to fix**

1. Go to **Server Settings → Roles**
2. Find the bot’s role
3. Drag it **above all roles** you want the bot to assign
4. Save changes
5. Re-run **Get Roles** or **Sync Roles**

> The bot cannot override Discord’s role hierarchy.

***

#### 2️⃣ The role is managed by another bot or integration

**What this means**

Roles created or controlled by:

* Other bots
* Discord apps
* Integrations

are marked as **managed** and **cannot be modified**.

**How to fix**

* Create a **new role manually** in Discord
* Do **not** assign it to another bot
* Use the new role in your role mappings

***

#### 3️⃣ The user does not meet the required threshold

**What this means**

The wallet was verified successfully, but the user’s holdings are **below the configured requirement**.

**How to check**

* Review the role’s contract ID
* Confirm the threshold value
* Verify the user’s on-chain balance manually if needed

***

#### 4️⃣ FT threshold misunderstood (decimals issue)

**What this means**

FT thresholds are **human-readable**, not raw on-chain units.

Example:

* If a token has 6 decimals
* A threshold of `100` means **100 tokens**, not `100000000`

**What to do**

* Enter thresholds exactly as humans read them
* The system automatically handles decimals

***

#### 5️⃣ Wrong contract type selected (FT vs NFT)

**What this means**

* An FT contract was configured as an NFT
* Or an NFT contract was configured as an FT

The system will reject mismatches during setup.

**How to fix**

* Double-check the contract type
* Re-add the role with the correct asset type

***

#### 6️⃣ User verified, but nothing changed

**What this means**

* Verification succeeded
* User does not qualify for any roles **yet**

**What to do**

* No action required
* Roles will be assigned once thresholds are met

***

### Sync ran, but roles didn’t change — why?

#### 1️⃣ User never verified a wallet

**Explanation**

Syncing only affects users who have **verified at least once** in the server.

**Solution**

Ask the user to run **Get Roles**.

***

#### 2️⃣ User changed wallets

**Explanation**

Syncing reuses the **last verified wallet**.

**Solution**

User must re-run **Get Roles** to link a new wallet.

***

#### 3️⃣ Sync cooldown active

**Explanation**

Sync can only run **once every 72 hours** per server.

**Solution**

Wait for the cooldown to expire.

***

### Setup failed — why?

#### 1️⃣ Invalid or non-existent contract ID

**Explanation**

The system validates contracts via the Hiro API.

**Solution**

* Ensure the contract ID is correct
* Confirm it exists on Stacks mainnet

***

#### 2️⃣ Contract is neither FT nor NFT

**Explanation**

Some contracts do not define tokens.

**Solution**

Only use contracts that define:

* `define-fungible-token`
* `define-non-fungible-token`

***

### Security & Trust

#### Does the system access private keys?

No. Wallet connections are read-only.

#### Are roles updated in real time?

No. Role updates occur during verification or sync.

***

### Still Stuck?

Before contacting support, verify:

1. Bot role hierarchy
2. Role is not managed
3. Contract ID correctness
4. User has verified
5. Sync cooldown status

{% hint style="info" %}
If the issue persists after checking the steps above:

1. Open a **support ticket** in the official Discord server
2. Include:
   * Server ID
   * Affected role name
   * Contract ID
   * What action you were trying to perform

If Discord support is unavailable, you can DM **@ghislo740** on Telegram.
{% endhint %}