FAQ & Troubleshooting

Roles were not assigned — why?

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

Setup failed — why?

Security & Trust

Still Stuck?

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

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.