Troubleshooting & FAQs

This guide covers common issues encountered when using or building on OmniSocial, with actionable steps to resolve them.

⚠️ Troubleshooting Matrix

Issue	Possible Cause	How to Fix
.omni alias not resolving	Subgraph may be out of sync or alias creation event not indexed	✅ Check if the subgraph is synced to the latest block✅ Verify alias event emitted from PersonaNFT or Wallet creation contract✅ Run a GraphQL query to check alias record
Metadata not loading (profile, persona, DAO)	IPFS gateway error or malformed metadata	✅ Inspect metadata link in browser or via ipfs.io/ipfs/...✅ Ensure correct JSON structure and schema✅ If uploading manually, use a pinning service like Pinata
Wallet not connecting	Wrong network or misconfigured RPC	✅ Make sure you're connected to Polygon zkEVM✅ Verify RPC URL is working (try in Metamask)✅ Switch to the correct chain ID (e.g., 1101)
Transaction fails or reverts	Gas limit too low, logic bug, or insufficient permissions	✅ Check error logs in console✅ Try increasing gas limit✅ Ensure connected persona/wallet has rights (e.g., DAO member, content owner)
Tips not sending / not received	Relayer wallet may be unfunded, or tipping contract failure	✅ Check relayer balance using block explorer✅ View emitted TipSent event in explorer or logs✅ Retry with more gas or directly from EOA
Proposal not executing	Timelock not expired or quorum not reached	✅ Confirm that the timelock delay (default: 24h) has passed✅ Verify quorum threshold met in votes✅ Review proposal status on /dao/[dao]/proposal/[id] page
Front-end not loading or crashes	JS error, bad data, or missing dependencies	✅ Run npm install to install all dependencies✅ Rebuild using npm run build✅ Check for missing .env vars or GraphQL schema mismatch
Subgraph errors or outdated data	Graph node needs sync or rebuild	✅ Run graph codegen && graph build && graph deploy ...✅ Check subgraph status at localhost:8000/subgraphs or hosted service✅ Delete and re-sync if stuck
Rep not updating	Reputation event not emitted or indexing delay	✅ Confirm grantReputation() or similar event was triggered✅ Wait for block confirmation✅ Query via subgraph to verify update
Post or comment not showing	Meta-tx may not have been relayed or data not indexed	✅ Confirm execute() was called by relayer✅ Check relayer logs✅ Inspect IPFS payload and subgraph sync status
Edition drop not working	Incorrect config or smart contract not deployed	✅ Validate drop params (supply, whitelist, etc.)✅ Ensure EditionDropFactory was used correctly✅ Check for emitted events like EditionCreated

❓ Frequently Asked Questions

Q: What if I lose my wallet?

A: If you used an OmniWallet with recovery configured, trigger account recovery via your guardian contact or recovery SBT. If not, the wallet is unrecoverable.

---

Q: Can I change my .omni alias or persona handle?

A: You can change your active persona handle (via NFT metadata), but .omni primary domains are fixed. Subdomains can be managed freely.

---

Q: Why does reputation decay over time?

A: OmniSocial uses a decay mechanism to reflect recent behavior over historical rep. Each rep domain has its own decay rate (see Reputation Ontology docs).

---

Q: Can I use OmniSocial from mobile?

A: Yes! The platform is optimized for mobile browsers and supports wallet connectors like WalletConnect and RainbowKit.

---

Q: Why didn’t my DAO proposal succeed?

A: Proposals fail if they:

• Don’t meet the quorum threshold

• Are executed too early (timelock delay not met)

• Get rejected by majority votes

---

Q: How do I get help?

A: Reach out on Discord, GitHub Issues, or check the full Docs.