Skip to Content
ReferenceTroubleshooting

Troubleshooting

Common errors and how to fix them.

SDK Errors

”ProfileNotFound”

Error: Transaction reverts with “ProfileNotFound”

Cause: The user doesn’t have a ChainSocial profile yet.

Solution: Create a profile before posting:

import { stringToHex, padHex } from 'viem'
 
const username = padHex(stringToHex('yourname'), { size: 32 })
await client.profile.createProfile(username)

“InsufficientFee”

Error: Transaction reverts with “InsufficientFee”

Cause: Fees are enabled and you didn’t send enough value.

Solution: Check fee config and send the required amount:

const config = await client.post.getFeeConfig()
 
if (config.isEnabled && config.feeToken === '0x0000000000000000000000000000000000000000') {
  // Native token fee - send value with transaction
  await client.post.createInlinePost('Hello!', PostVisibility.PUBLIC, config.postFee)
}

“ContentTooLong”

Error: Transaction reverts with “ContentTooLong”

Cause: Inline content exceeds 4KB limit.

Solution: Use IPFS storage for larger content:

// Upload to IPFS first
const cid = await uploadToIpfs(largeContent)
 
// Create content reference
const contentId = await client.content.createIpfsContent(cid, 'text/plain', contentLength)
 
// Create post with content reference
await client.post.createPost(contentId, PostVisibility.PUBLIC)

“Chain mismatch”

Error: Chain mismatch: publicClient=8453, walletClient=1

Cause: Your publicClient and walletClient are configured for different chains.

Solution: Ensure both clients use the same chain:

import { base } from 'viem/chains'
 
const publicClient = createPublicClient({
  chain: base,  // Same chain
  transport: http()
})
 
const walletClient = createWalletClient({
  chain: base,  // Same chain
  transport: http()
})

“worldAddress is required”

Error: worldAddress is required

Cause: Missing configuration when creating the client.

Solution: Provide the World contract address:

const client = createChainSocialClient({
  worldAddress: '0x7405fCbEc24C00278b7e821Ace222f5CFfa6c6eA',
  publicClient,
  walletClient
})

API Errors

404 Not Found

Possible causes:

  • Profile or post doesn’t exist
  • Invalid address format
  • Content hasn’t been indexed yet (indexer lag)

Solution:

  • Verify the address/ID is correct
  • Wait a few seconds and retry (indexer may be catching up)

401 Unauthorized

Cause: Accessing protected endpoint without authentication.

Solution: Message endpoints require authentication:

const response = await fetch(`/api/messages/${address}/conversations`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

429 Rate Limited

Cause: Too many requests.

Solution: Implement backoff and respect rate limits:

const response = await fetch('/api/feed')
 
if (response.status === 429) {
  const resetTime = response.headers.get('X-RateLimit-Reset')
  const waitMs = (parseInt(resetTime) * 1000) - Date.now()
  await new Promise(r => setTimeout(r, waitMs))
  // Retry
}

Transaction Issues

Transaction Pending Forever

Possible causes:

  • Gas price too low
  • Nonce issues

Solution:

  • Check transaction on block explorer
  • If stuck, speed up with higher gas or cancel with same nonce

Transaction Reverted

Debugging steps:

  1. Check the revert reason in the error message
  2. Verify you have a profile (most actions require one)
  3. Check if fees are enabled and you’re sending enough
  4. Verify you’re not blocked by the recipient (for DMs)
  5. Check delegation permissions (for on-behalf-of actions)

React Integration Issues

”ChainSocial client not available”

Cause: Accessing the client before provider is ready.

Solution: Check for null client:

const client = useChainSocialClient()
 
if (!client) {
  return <div>Loading...</div>
}
 
// Now safe to use client

Client Changes on Every Render

Cause: Creating new client instance without memoization.

Solution: Use useMemo:

const client = useMemo(() => {
  if (!publicClient) return null
  return createChainSocialClient({ worldAddress, publicClient, walletClient })
}, [publicClient, walletClient])

Indexer Issues

Posts Not Appearing

Possible causes:

  • Indexer is behind chain head
  • Post was just created (indexer lag)
  • Transaction hasn’t confirmed yet

Solution:

  • Check transaction confirmed on block explorer
  • Wait 10-30 seconds for indexer to catch up
  • Check /api/health for indexer status

Stale Data

Cause: Indexer fell behind or restarted.

Solution:

  • Check /api/health endpoint for indexer status
  • Report to ChainSocial team if persistent

Common Patterns

Retry with Backoff

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (i === maxRetries - 1) throw error
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)))
    }
  }
  throw new Error('Max retries exceeded')
}
 
// Usage
const result = await withRetry(() => client.post.createInlinePost('Hello'))

Check Profile Exists

async function ensureProfile(client, username) {
  try {
    const response = await fetch(`/api/profiles/${client.walletClient.account.address}`)
    if (!response.ok) {
      // Create profile
      const usernameBytes = padHex(stringToHex(username), { size: 32 })
      await client.profile.createProfile(usernameBytes)
    }
  } catch (error) {
    console.error('Profile check failed:', error)
    throw error
  }
}

Still stuck? Check the ChainSocial GitHub  for known issues or open a new issue.

Data Types & Enums