Troubleshooting

Common issues and solutions when building with Civra.

Platform Issues

Can't Sign In

Symptoms:

• Login button doesn't work
• Redirect loop
• "Authentication failed" error

Solutions:

1. Clear Browser Cache

   Chrome: Ctrl+Shift+Delete
   Firefox: Ctrl+Shift+Delete
   Safari: Cmd+Option+E

2. Try Incognito/Private Mode

   Chrome: Ctrl+Shift+N
   Firefox: Ctrl+Shift+P
   Safari: Cmd+Shift+N

3. Check Third-Party Cookies

   Settings → Privacy → Allow third-party cookies

4. Try Different Auth Method

   If Google fails → Try GitHub

5. Check Status Page

   https://status.civra.dev

Credits Not Working

Symptoms:

• Credits not deducted
• "Insufficient credits" when you have credits
• Credits not resetting

Solutions:

1. Refresh Usage Dashboard

   Settings → Usage → Click refresh icon

2. Check Billing Date

   Credits reset on your billing anniversary
   Settings → Billing → View next reset date

3. Clear Cache

   Sometimes cached credit balance shows
   Hard refresh: Ctrl+Shift+R

4. Contact Support

   If credits were deducted incorrectly:
   support@civra.dev with transaction ID

Project Won't Load

Symptoms:

• Stuck on "Loading project..."
• Blank preview window
• "Project not found" error

Solutions:

1. Check Project Status

   Dashboard → Projects → Check status indicator
   
   Creating: Still being generated
   Active: Should load
   Stopped: Click "Start" to wake up
   Error: Check error message

2. Restart Project

   Project menu → Restart
   Wait 30-60 seconds for sandbox to start

3. Check Console

   F12 → Console → Look for errors

4. Try Different Browser

   Sometimes browser extensions block preview

5. Contact Support

   If project is corrupted:
   support@civra.dev with project ID

AI Generation Issues

AI Not Responding

Symptoms:

• Message sent but no response
• Stuck on "AI is thinking..."
• Timeout error

Solutions:

1. Check Credits

   Dashboard → Usage
   Ensure you have message credits remaining

2. Wait for Completion

   Complex requests take 30-120 seconds
   Don't refresh during generation

3. Check Message Length

   Very long prompts may timeout
   Break into smaller requests

4. Retry Request

   Click retry button
   Or rephrase and send again

Wrong Code Generated

Symptoms:

• AI misunderstood request
• Code doesn't match description
• Wrong technology used

Solutions:

1. Be More Specific

   ❌ "Add a button"
   ✅ "Add a blue 'Connect Wallet' button in the navbar"

2. Clarify Requirements

   "I meant change the color, not the text"

3. Reference Examples

   "Make it look like Uniswap's swap interface"

4. Use Step-by-Step

   Break complex features into steps:
   1. Create contract
   2. Add function
   3. Update UI

5. Provide Context

   "I'm building an NFT marketplace.
   Add a listing page with grid layout."

Generation Fails

Symptoms:

• "Generation failed" error
• Code partially generated
• Dependencies won't install

Solutions:

1. Check Error Message

   Read the specific error
   Often tells you what went wrong

2. Common Errors:

   Dependency Conflict:

   "Tell AI: Remove package X and use Y instead"

   Syntax Error:

   "Fix the syntax error in [file]"

   Import Error:

   "Update imports to use correct package"

3. Start Fresh

   If project is broken:
   Create new project
   Copy working code

Web3 & Smart Contract Issues

Wallet Won't Connect

Symptoms:

• "Connect" button doesn't work
• MetaMask not detected
• Connection rejected

Solutions:

1. Install/Update MetaMask

   https://metamask.io/download
   Ensure version 11+ for best compatibility

2. Unlock MetaMask

   Open MetaMask extension
   Enter password
   Try connecting again

3. Check Network

   MetaMask → Network dropdown
   Ensure on correct network (Ethereum, Polygon, etc.)

4. Clear MetaMask Cache

   MetaMask → Settings → Advanced → Reset
   WARNING: Have seed phrase backed up!

5. Try Different Wallet

   If MetaMask fails:
   Try Coinbase Wallet or WalletConnect

Transactions Failing

Symptoms:

• "Transaction reverted"
• "Insufficient funds"
• "Gas estimation failed"

Solutions:

1. Insufficient Funds

   Check wallet balance
   Ensure enough ETH for gas + transaction
   Get testnet ETH from faucet

2. Gas Price Too Low

   Increase gas price in MetaMask
   Or let MetaMask auto-suggest

3. Contract Error

   Read revert message:
   
   "Insufficient balance" → Add tokens
   "Not authorized" → Check permissions
   "Paused" → Contract paused by owner

4. Wrong Network

   Switch to correct network:
   Contract on Polygon? → Use Polygon network

5. Slippage Too Low (DEX)

   Increase slippage tolerance:
   Settings → Slippage → 1-5%

Smart Contract Issues

Contract Not Deploying:

1. Check Gas

   Large contracts need more gas
   Increase gas limit in deployment

2. Check Constructor Args

   Ensure constructor arguments correct
   Match types (address, uint256, etc.)

3. Check Network

   Deploying to testnet or mainnet?
   Have enough native token?

Contract Not Verified:

1. Auto-Verification Failed

   Civra attempts auto-verification
   If failed, verify manually on Etherscan

2. Manual Verification

   1. Go to Etherscan
   2. Find contract address
   3. Verify & Publish
   4. Upload source code
   5. Match compiler settings

Function Not Working:

1. Check Permissions

   onlyOwner functions need owner address
   Check if wallet is authorized

2. Check State

   Contract paused? → Unpause first
   Tokens approved? → Approve before transfer

3. Check Arguments

   Correct types and values?
   Address valid?
   Amount not zero?

Preview & Deployment Issues

Preview Not Loading

Symptoms:

• Blank preview window
• "Failed to load preview"
• 502/504 errors

Solutions:

1. Wait for Server Start

   Dev server takes 30-60 seconds to start
   Check progress indicator

2. Restart Project

   Project menu → Restart
   Starts fresh dev server

3. Check Build Errors

   Click "View Logs"
   Look for TypeScript errors
   Look for missing dependencies

4. Clear Build Cache

   Tell AI: "Clear the build cache and restart"

Deployment Fails

Symptoms:

• "Deployment failed"
• Build errors
• Network timeout

Solutions:

1. Check Build Output

   Read build logs
   Fix TypeScript errors
   Fix ESLint warnings

2. Check Environment Variables

   Ensure all required env vars set:
   - API keys
   - Contract addresses
   - RPC URLs

3. Check File Size

   Large builds may timeout
   Optimize images
   Remove unused dependencies

4. Try Again

   Network issues are temporary
   Click "Retry Deployment"

Performance Issues

Slow AI Responses

Causes:

• High platform load
• Complex requests
• Large codebase

Solutions:

1. Be Concise

   Shorter, focused prompts respond faster

2. Off-Peak Hours

   Try during off-peak times
   Generally faster late night UTC

3. Upgrade Plan

   Pro/Elite plans get priority processing

Slow Preview

Causes:

• Large dependencies
• Unoptimized code
• Memory issues

Solutions:

1. Optimize Dependencies

   Tell AI: "Remove unused dependencies"

2. Code Splitting

   Tell AI: "Implement code splitting for faster loads"

3. Image Optimization

   Tell AI: "Optimize images using Next.js Image component"

Error Messages Decoded

Common Errors

"Insufficient credits"

Solution: Upgrade plan or wait for monthly reset
Check: Settings → Usage

"Project limit reached"

Solution: Delete old projects or upgrade from Free plan
Free plan: 3 projects max
Paid plans: Unlimited

"Generation timeout"

Solution: Request was too complex
Break into smaller requests
Or try again

"Network error"

Solution: Check internet connection
Try again in a few moments
Check status.civra.dev

"Invalid signature"

Solution: Wallet signature verification failed
Ensure correct wallet connected
Try disconnecting and reconnecting

"Contract execution reverted"

Solution: Smart contract rejected transaction
Read revert reason
Check requirements (balance, approval, etc.)

"Nonce too low"

Solution: Transaction nonce conflict
Reset MetaMask account
Settings → Advanced → Reset Account

"Replacement transaction underpriced"

Solution: Gas price too low for replacement
Cancel original transaction first
Or increase gas significantly (10%+)

Getting Help

Self-Service

1. Search Docs

   https://docs.civra.dev/search

2. Check FAQ

   /getting-started/faq

3. Community Discord

   Ask in #help channel
   Community often responds quickly

Contact Support

Email Support:

support@civra.dev

Include:
- Account email
- Project ID (if applicable)
- Steps to reproduce
- Screenshots/errors
- Browser and OS

Response Times:

• Free: 3-5 business days
• Starter: 2-3 business days
• Builder: 1-2 business days
• Pro: <24 hours
• Elite: <4 hours

Discord Support:

https://discord.gg/civra

#help channel for community
#support-tickets for staff

Emergency Support (Elite only):

emergency@civra.dev
Phone support available
<1 hour response time

Reporting Bugs

Bug Report Template

**Describe the bug:**
Clear description of what's wrong

**To Reproduce:**
1. Go to '...'
2. Click on '....'
3. See error

**Expected behavior:**
What should happen

**Screenshots:**
Attach if applicable

**Environment:**
- Browser: Chrome 120
- OS: macOS 14
- Plan: Builder
- Project ID: abc123

**Additional context:**
Any other relevant info

Where to Report:

• GitHub: https://github.com/civra/civra/issues
• Discord: #bug-reports
• Email: bugs@civra.dev

Known Issues

Current Known Issues

1. Preview frame resize lag (Minor)

   • Workaround: Refresh preview
   • Fix ETA: Next release

2. File browser folder expansion (Minor)

   • Workaround: Click twice
   • Fix ETA: This week

3. Dark mode flash on load (Cosmetic)

   • Workaround: None needed
   • Fix ETA: Next release

See live status: status.civra.dev/known-issues

Best Practices to Avoid Issues

1. Save Work Frequently

   Chat history auto-saves
   But export important code

2. Test Incrementally

   Test after each major change
   Don't wait until the end

3. Use Version Control

   Connect GitHub (Starter+)
   Commit regularly
   Easy rollback if needed

4. Monitor Credits

   Check before long sessions
   Set up usage alerts

5. Start with Templates

   Pre-tested, working code
   Less likely to have issues

Next Steps

• Contact Support
• Join Discord
• View Status Page
• Read FAQ