Debugging & Fixing Errors

Things will go wrong during development. The AI will sometimes produce errors, get stuck, or build something different from what you expected. This page covers the most common issues and how to handle them efficiently.

How Primio handles errors

When the AI detects a compilation error in your app, it automatically tries to fix it. You’ll see tool usage messages in the chat as the AI reads error logs, identifies the issue, and modifies code. Most errors are resolved within one or two fix cycles without any action from you.

This is normal behavior. Let the AI work through it. Only intervene if the fix cycle repeats more than two or three times — that’s a loop.

When the AI gets stuck in a loop

Caution

If you see the AI making repeated similar changes without resolving the error, it’s stuck in a loop. This consumes tokens rapidly. Hit the Stop button immediately to halt generation, then follow the steps below.

An error-fixing loop looks like this: the AI changes a file, gets the same (or a similar) error, changes the file again, gets another error, and keeps going. Each cycle costs tokens, and the chances of the AI breaking out on its own decrease with each attempt.

What to do:

1. Roll back

   Revert to the last working state — the agent message before things broke. See Rollback.

2. Rephrase your request

   The original prompt likely asked for something the AI couldn’t implement in one shot. Break it into smaller, simpler steps.

3. Try a different approach

   If the AI struggled with a specific implementation, describe the feature differently. Instead of “add a complex animation,” try “add a simple fade-in when the screen loads.”

4. Switch models

   If you’re using Sonnet and the task is complex, switch to Opus. More capable models handle tricky code problems better. See Model Selection.

Preview vs. device discrepancies

The web preview is a Flutter web build running in your browser. It is not device emulation. Your app can look and behave differently on a real phone.

Things that only work on a real device:

• Camera and sensors (gyroscope, accelerometer, GPS)
• Push notifications
• Biometric authentication (fingerprint, face ID)
• Native sharing and system sheets
• App-to-app deep links

Things that may look or feel different:

• Scroll performance and physics
• Animations and transitions (especially complex ones)
• Platform-specific UI elements (Material on Android, Cupertino on iOS)
• Screen sizes, notches, and safe areas
• Touch target sizes and gesture behavior
• Font rendering

Solution: Test on a real device periodically, not just at the end.

• Build an APK (20K tokens) and install on your Android phone via the QR code
• Use Web Hosting (free) to open your app in any mobile browser
• Build an IPA (40K tokens) and test via TestFlight on iPhone

Note

Don’t wait until you’re done building to test on a device. Test every few iterations to catch device-specific issues early — it’s cheaper than discovering them at the end and rolling back through layers of features.

Bottom overflow

Flutter has a strict layout engine. When the children of a vertical layout (a Column, a custom widget, or a fixed-height container) take up more space than the parent allows, Flutter doesn’t silently clip the content — it renders a yellow-and-black “BOTTOM OVERFLOWED BY X.0 PIXELS” warning banner across the bottom of the widget.

This commonly happens when:

• A screen has more content than fits the viewport (especially on smaller devices)
• A fixed-height container holds too many widgets or widgets with large padding
• Font sizes, icons, or spacing push total height past the available space

The overflow is cosmetic in the preview — the app still runs — but it signals a real layout problem that will show on actual devices too.

How to fix it in Primio:

1. Screenshot the error

   Use the preview’s screenshot button (camera icon, bottom-right corner) and choose Add to prompt, or take a regular screenshot and drag it into the chat.

2. Describe the problem

   Something like: “This widget is overflowing at the bottom — please fix the layout so everything fits.”

3. Let the AI fix it

   The AI will read the relevant layout file, calculate the available space, and adjust. Common fixes include reducing widget sizes, tightening padding and spacing, wrapping content in a SingleChildScrollView, increasing the parent container’s height, or replacing fixed sizes with Expanded or Flexible widgets.

4. Check the result — a second round may be needed

   Most overflows are fixed in one round. If the AI shrinks content but the container is still too small (or vice versa), send a follow-up: “It’s still overflowing” with a new screenshot. The second pass typically resolves it.

Tip

Attaching a screenshot is the single most effective thing you can do. The AI can see the exact overflow amount and the surrounding layout, which lets it calculate the fix precisely rather than guessing.

Incomplete AI responses

Sometimes the AI completes only part of your request — it builds the screen but skips the navigation, or adds three of the five features you asked for.

Why it happens: Complex multi-part requests can exceed the AI’s attention span in a single response. The AI finishes what it considers the primary task and stops.

What to do:

• Send a follow-up: “You didn’t finish the settings page — please complete it”
• Or simply: “Continue where you left off”
• For future requests, keep each message focused on a single feature. See Prompting Fundamentals.

Build failures

AAB/APK build fails — missing icon

Both Google Play (AAB) and direct installs (APK) need an app icon. If you haven’t set one, the build may fail or produce an app with a broken icon. Upload a custom icon in Workspace → App Icon before building. See App Icon.

IPA build fails — certificate limit

Apple allows a maximum of 3 active iOS distribution certificates per account. If you’ve hit the limit, revoke an unused certificate in your Apple Developer Portal and try again.

IPA build fails — wrong credentials

Double-check your App Store Connect API credentials:

• The .p8 file should be the original key file downloaded from Apple (you can only download it once)
• The Key ID is exactly 10 characters
• The Issuer ID is a UUID found in App Store Connect → Users and Access → Integrations → App Store Connect API

See the iOS credentials guide in the Publish section for step-by-step setup.

Build fails with compilation errors

The AI may have introduced a code issue that wasn’t caught in the preview but breaks the native build. Roll back to the last known-good state and try a simpler approach. If the same build error persists after rollback, the issue may be in an earlier change — try rolling back further.

App crashes after publishing

If your app crashes on a real device:

1. Try to reproduce in the web preview. If the crash also happens in the preview, describe the steps to the AI and ask it to fix the issue.
2. Check if it’s device-specific. Features that depend on hardware (camera, sensors) or platform APIs (push notifications, in-app purchases) won’t work in the preview. Tell the AI what’s happening: “The app crashes when I open the camera on my Android phone.”
3. Ask the AI to investigate. “My app crashes when I open the profile screen. Can you check for potential null pointer issues or missing data handling?”
4. If persistent, roll back and rebuild. Go back to a known-good state and add features more incrementally, testing on a real device after each addition.

Unexpected UI changes during refactoring

Caution

The refactor tool — used when the AI splits large files into smaller ones — can sometimes change your UI unexpectedly. If your layout looks different after the AI refactors code, roll back immediately. It’s faster than trying to fix the changed UI through follow-up prompts.

This happens because the AI restructures code during refactoring and may inadvertently change widget trees, default values, or styling in the process. The functionality might be identical, but the visual result shifts.

When to contact support

Some issues can’t be resolved through prompts or rollbacks:

• Tokens depleted unexpectedly with no visible AI activity
• A build fails with the same error repeatedly, even after rollback and a clean rebuild
• Signing key issues that prevent builds or store submissions
• Account or billing problems

Email support@primio.dev with your project ID and a description of the issue.

Next steps

Rollback

Learn to use rollback effectively — your most important tool when things go wrong.

Building a Complete App

Follow the phased approach to minimize errors and build efficiently.

Getting the Best Results

Prevent common issues before they happen — strategies for effective AI collaboration.