# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zeroauthority.xyz/nova-bot/token-gated-discord-roles/faq-and-troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.