<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Stacklyn Labs Blog]]></title><description><![CDATA[aPractical Flutter engineering from Stacklyn Labs: offline-first architecture, local databases (hive_ce, Isar, drift), App Store and Google Play releases, and l]]></description><link>https://stacklynlabs.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Mon, 16 Nov 2026 06:19:59 GMT</lastBuildDate><atom:link href="https://stacklynlabs.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Optimizing Flutter App Performance for Older Mobile Devices]]></title><description><![CDATA[Frame drops, Riverpod rebuilds, memory leaks and image caching: how to keep a Flutter app smooth on five-year-old budget phones.]]></description><link>https://stacklynlabs.hashnode.dev/optimizing-flutter-app-performance-for-older-mobile-devices</link><guid isPermaLink="true">https://stacklynlabs.hashnode.dev/optimizing-flutter-app-performance-for-older-mobile-devices</guid><category><![CDATA[Flutter]]></category><category><![CDATA[performance]]></category><category><![CDATA[Riverpod]]></category><category><![CDATA[Dart]]></category><category><![CDATA[Android]]></category><dc:creator><![CDATA[Stacklyn Labs]]></dc:creator><pubDate>Mon, 16 Nov 2026 02:01:16 GMT</pubDate><content:encoded><![CDATA[<p><em>Originally published on <a href="https://stacklynlabs.com/blog/optimizing-flutter-app-performance-for-older-mobile-devices/">Stacklyn Labs</a>.</em></p>
<p>You just finished building your latest Flutter application. You load it up on your shiny new flagship phone, and it’s an absolute masterpiece. The animations are buttery smooth, the lists scroll flawlessly, and the whole experience feels incredibly premium.</p>
<p>Then, you hand it to a user with a five-year-old budget Android device. Suddenly, your masterpiece is stuttering, dropping frames, and draining the battery in twenty minutes.</p>
<p>If you want your app to succeed in the real world, it needs to perform beautifully on the devices real people actually use. At Stacklyn Labs, we specialize in building cross-platform mobile apps and premium templates. We know firsthand that true quality isn't tested on the latest hardware it’s tested on legacy devices struggling with limited RAM and weaker CPUs.</p>
<p>If you want to truly optimize your Flutter app and lock in that flawless 60fps across the board, you have to be intentional about your code. This technical guide covers how to eliminate frame drops, fix memory issues, and squeeze maximum efficiency out of your state management. How your app stores and reads local data affects memory too, so if that is where your budget goes, start with our <a href="https://stacklynlabs.com/blog/building-zero-latency-mobile-apps-hive-vs-isar-vs-sqlite-choosing-a-flutter-local-database-in-2026/">Flutter local database comparison</a>.</p>
<p>Here is how you can ensure your app runs like a dream on older mobile devices.</p>
<h2>The Silent Killers: Frame Drops and UI Jank</h2>
<p>When a legacy device struggles to render your app at 60 frames per second, the user experiences "jank." This usually happens because we are asking the device's GPU to do too much heavy lifting. Older phones simply don't have the processing power to handle unnecessary offscreen rendering.</p>
<p>Two of the biggest culprits in Flutter are the <code>Opacity</code> and <code>ClipRRect</code> widgets.</p>
<p>When you wrap a widget in <code>Opacity</code>, Flutter is forced to render that widget to an offscreen buffer before painting it back to the screen with the transparency applied. On a mid-range or older device, doing this inside a scrolling list will absolutely destroy your frame rate.</p>
<p>Instead of doing this:</p>
<p>Dart</p>
<pre><code>// Bad for performance on older devices
Opacity(
  opacity: 0.5,
  child: Container(
    color: Colors.blue,
    width: 100,
    height: 100,
  ),
)
</code></pre>
<p>Do this:</p>
<p>Dart</p>
<pre><code>// Much better for Flutter app performance
Container(
  color: Colors.blue.withOpacity(0.5),
  width: 100,
  height: 100,
)
</code></pre>
<p>By applying the opacity directly to the color, Flutter skips the offscreen rendering step entirely. The same logic applies to rounded corners. Instead of indiscriminately wrapping everything in a <code>ClipRRect</code>, use the <code>borderRadius</code> property inside a <code>BoxDecoration</code> whenever possible. These tiny adjustments add up fast.</p>
<h2>Squeezing Every Drop of Riverpod Performance</h2>
<p>State management is the backbone of any serious application, but it’s also a massive source of performance bottlenecks if used incorrectly. Riverpod is a fantastic tool, but you have to be careful about how often it triggers widget rebuilds.</p>
<p>Older processors struggle when they have to constantly rebuild large portions of the widget tree. If you have a list of a hundred items, and changing the state of one item causes the entire screen to rebuild, you are going to see a massive performance hit.</p>
<p>To maximize Riverpod performance, you need to use the <code>select</code> method.</p>
<p>By default, when you use <code>ref.watch(myProvider)</code>, your widget will rebuild anytime <em>anything</em> inside that provider changes. But what if your widget only cares about a single string or integer inside a massive state object? That is where <code>select</code> comes in.</p>
<p>Dart</p>
<pre><code>// Rebuilds ONLY when the 'userName' property changes
final userName = ref.watch(
  userProvider.select((user) =&gt; user.userName),
);
</code></pre>
<p>By filtering the state, you tell Flutter to ignore all other changes. The widget will remain untouched unless that specific piece of data updates. Implementing this properly throughout your app drastically reduces the CPU load on older devices, keeping your UI incredibly snappy.</p>
<h2>Plugging the Leaks: How to Prevent a Flutter Memory Leak</h2>
<p>A memory leak happens when your application holds onto objects that are no longer needed, preventing the Dart garbage collector from freeing up that memory.</p>
<p>On a modern device with 8GB of RAM, you might get away with a sloppy memory footprint for a little while. But on an older phone with only 2GB or 3GB of RAM, a Flutter memory leak is a death sentence. The operating system will aggressively kill your app in the background, or worse, crash it entirely while the user is trying to use it.</p>
<p>The most common causes of memory leaks in Flutter are un-disposed controllers, active timers, and open stream subscriptions.</p>
<p>Whenever you initialize an <code>AnimationController</code>, a <code>TextEditingController</code>, or a <code>ScrollController</code>, you must clean it up when the widget is removed from the screen.</p>
<p>Dart</p>
<pre><code>class _MyFormState extends State&lt;MyForm&gt; {
  final TextEditingController _emailController = TextEditingController();

  @override
  void dispose() {
    // If you forget this, you've got a memory leak!
    _emailController.dispose();
    super.dispose();
  }
}
</code></pre>
<p>You should also be highly suspicious of <code>BuildContext</code>. Never store a <code>BuildContext</code> in a long-lived variable or a singleton. If you hold onto the context of a screen after the user has navigated away from it, that entire screen and all of its widgets will remain trapped in memory.</p>
<p>When compiling and testing your latest Dart 3.11.1 code on your Windows machine, always keep an eye on the Flutter DevTools Memory tab. It is the best way to proactively spot a rising memory graph before it reaches your users.</p>
<h2>Image Caching: Don't Let Assets Choke Your App</h2>
<p>Images are surprisingly heavy. One of the easiest ways to accidentally cripple your Flutter app performance on a low-end device is to mishandle image assets.</p>
<p>Let’s say you are building a social feed, and you load a high-resolution 4K image from a server to display in a tiny 50x50 user avatar. By default, Flutter will decode that massive image into memory at its full, uncompressed resolution. A few of those on a screen, and an older phone will instantly run out of memory.</p>
<p>To fix this, you should always cache your network images and dictate the exact size you need them to be decoded at. Packages like <code>cached_network_image</code> are great, but the real magic happens when you use the <code>memCacheWidth</code> and <code>memCacheHeight</code> properties.</p>
<p>Dart</p>
<pre><code>CachedNetworkImage(
  imageUrl: "https://example.com/huge-image.jpg",
  memCacheWidth: 150, // Decodes the image at a smaller size
  memCacheHeight: 150,
  fit: BoxFit.cover,
)
</code></pre>
<p>This tells the engine to resize the image during the decoding process. The visual result on the screen is identical, but the memory footprint is a tiny fraction of what it would have been. This one trick alone can often solve the worst scrolling lag on older Android devices.</p>
<p>Getting every list, controller and image right on a 2GB test phone is slow, repetitive work, and it hurts most in an app that stays open all day, like a point-of-sale terminal on a cheap handset. <a href="https://stacklynlabs.com/product/stockpilot/">StockPilot</a> runs its whole checkout, stock and receipt flow on the device with a local Hive database, so a weak phone is never waiting on a network round trip. On that kind of setup the receipt printer is often the next thing to go wrong, and our checklist for <a href="https://stacklynlabs.com/blog/flutter-thermal-printer-troubleshooting/">a Flutter Bluetooth thermal printer that isn't printing</a> works through the usual causes.</p>
<h2>How Premium Templates Hit 60fps</h2>
<p>When you are selling code to other developers, performance has to be baked into the very foundation of the architecture, not just treated as an afterthought.</p>
<p>At Stacklyn Labs, we build commercial templates that developers rely on to launch real businesses. When we engineered premium templates like <strong>Zenith</strong>, <strong>StockPilot</strong>, <strong>SubZero</strong>, and <strong>Rent Folio</strong>, we strictly adhered to these optimization principles.</p>
<p>We don’t just test our templates on the fastest simulators. We actively profile them to ensure that background tasks are handled cleanly, state rebuilds stay narrow, and heavy widget trees are broken down into <code>const</code> constructors wherever possible.</p>
<p>A properly optimized app feels completely different. It responds to touch instantly, lists glide smoothly under your thumb, and users aren't left staring at a frozen screen while a background process hogs the main thread. By treating legacy devices as your baseline standard, you guarantee an exceptional experience for everyone else.</p>
<h2>Build Something Flawless</h2>
<p>You don't need a massive team to optimize a Flutter app; you just need good habits. By avoiding heavy offscreen rendering, utilizing targeted Riverpod state rebuilds, religiously disposing of your controllers, and resizing your network images, you can easily deliver a world-class experience to users on older hardware.</p>
<p>If you are looking to accelerate your next project, you shouldn't have to worry about fixing someone else's messy code. Start with a foundation that is already engineered for maximum performance.</p>
<p><strong>Ready to see what a truly optimized Flutter application feels like?</strong> Explore our collection of high-performance templates at Stacklyn Labs, or reach out to us for expert development and consulting to take your current app to the next level.</p>
<p><strong>Suggested Meta Description:</strong></p>
<p>Learn how to optimize Flutter app performance for older devices. Discover technical tips to fix frame drops, prevent memory leaks, and maximize Riverpod performance.</p>
<h2>References &amp; Further Reading</h2>
<ul>
<li>Flutter Performance Profiling (Official Docs): An essential resource directly from the Flutter team that covers UI performance profiling, tracing dropped frames, and diagnosing raster cache issues on older hardware.</li>
<li>How to Reduce Provider/Widget Rebuilds (Riverpod Docs): The official documentation breaks down exactly how to use the <code>.select</code> method to filter state changes, ensuring your heavy widgets only rebuild when absolutely necessary.</li>
<li>Flutter Performance Best Practices: A Comprehensive Guide: This detailed walkthrough explains the hidden costs of expensive layout passes, the <code>saveLayer()</code> function, and why widgets like <code>Opacity</code> and <code>ClipRRect</code> should be handled with extreme caution.</li>
<li>A Guide on Optimising Memory Performance Using Flutter DevTools: A practical look into utilizing the DevTools Memory View to identify large heap allocations, track down stubborn memory leaks, and monitor exactly where your app's RAM is going.</li>
<li>Performance Profiling in Flutter: A great breakdown of how to use the Timeline and Memory views in DevTools to catch expensive computations and rendering work before they cause jank for your users.</li>
</ul>
<hr />
<p><em>Further reading: <a href="https://stacklynlabs.com/blog/riverpod-vs-bloc-in-2026-the-ultimate-flutter-state-management-guide/">Riverpod vs BLoC in 2026</a></em></p>
]]></content:encoded></item><item><title><![CDATA[Handling Data Synchronization and Conflict Resolution in Offline Apps]]></title><description><![CDATA[Optimistic UI, a Hive-backed queue, background sync with retries, and conflict strategies like last-write-wins for offline Flutter apps.]]></description><link>https://stacklynlabs.hashnode.dev/handling-data-synchronization-and-conflict-resolution-in-offline-apps</link><guid isPermaLink="true">https://stacklynlabs.hashnode.dev/handling-data-synchronization-and-conflict-resolution-in-offline-apps</guid><category><![CDATA[Flutter]]></category><category><![CDATA[offline first]]></category><category><![CDATA[hive]]></category><category><![CDATA[Dart]]></category><category><![CDATA[Mobile Development]]></category><dc:creator><![CDATA[Stacklyn Labs]]></dc:creator><pubDate>Sun, 15 Nov 2026 08:42:17 GMT</pubDate><content:encoded><![CDATA[<p><em>Originally published on <a href="https://stacklynlabs.com/blog/handling-data-synchronization-and-conflict-resolution-in-offline-apps/">Stacklyn Labs</a>.</em></p>
<p>Ever used an app that completely froze the moment your train went into a tunnel? Or worse, one that threw an ugly error screen just because you lost bars on a road trip? It’s a frustrating experience, and honestly, it’s a quick way to lose user trust. People today expect applications to work flawlessly, regardless of their connection status. They don't care if they are offline; they just want to tap a button and see things happen.</p>
<p>This is exactly where offline-first architecture steps in to save the day. At Stacklyn Labs, we specialize in creating robust, cross-platform mobile apps using Flutter and Dart. Because of this, we know firsthand that building an app that handles network drops gracefully is an absolute requirement for a premium user experience, not just a nice-to-have feature.</p>
<p>In this post, we are taking a deep dive into the mechanics of offline data synchronization. We will look at how you can sync local Hive data with remote APIs, set up reliable background polling, implement smart retry logic, and handle the inevitable collisions with standard offline first conflict resolution strategies like Last-Write-Wins. Let’s get into it.</p>
<p>All of this sits on top of a bigger decision every Flutter team has to make first: which local database actually anchors that sync layer. We cover that tradeoff in our guide to <a href="https://stacklynlabs.com/blog/building-zero-latency-mobile-apps-hive-vs-isar-vs-sqlite-choosing-a-flutter-local-database-in-2026/">which Flutter local database to build a sync layer on</a>.</p>
<h2>The Magic of Optimistic UI in Flutter</h2>
<p>Before we even talk about databases and APIs, we need to talk about user perception. When a user hits "Save," they shouldn't have to stare at a spinning loading wheel while the app begs the server for a response.</p>
<p>Instead, you should leverage an optimistic UI. In an optimistic ui flutter implementation, your app assumes the network request will eventually succeed. You update the local screen instantly. The user sees their new note, their sent message, or their updated profile picture right away, feeling like the app is lightning fast. Behind the scenes, the app is quietly queuing up the actual data payload to be sent to your remote API.</p>
<p>If the network is down? No problem. The UI still updates, the user keeps working, and the app takes on the responsibility of sending that data later. But to pull off this magic trick safely, you need a highly reliable local storage system.</p>
<h2>Building the Engine: Local Storage with Hive</h2>
<p>To make an offline-first app work, the device itself has to become the temporary source of truth. For Flutter developers, Hive is often the go-to tool for this job. It’s a lightweight, incredibly fast NoSQL database written entirely in Dart.</p>
<p>When syncing local Hive data with remote APIs, the standard approach is to create a queue system. Every time the user makes an edit or creates a record offline, you save that record into a Hive box. Crucially, you append a <code>pendingSync</code> flag or a similar metadata marker to it.</p>
<p>This flag isolates local mutations from your main, already-synced data. Your app now has a clear to-do list. It knows exactly which items are perfectly in sync with the cloud, and which items are waiting in the departure lounge. Whether you are running the latest Dart SDK 3.11.1 or maintaining an older codebase, building this queue locally ensures that no user input is ever lost to the void of a disconnected network.</p>
<h2>Keeping Things Moving: Flutter Background Sync and Retry Logic</h2>
<p>So, the user has made changes, and those changes are safely sitting in Hive. How do we get them to the server?</p>
<p>The first step is connectivity detection. By utilizing packages like <code>connectivity_plus</code>, your app can actively listen for network changes. The moment the device reconnects to Wi-Fi or cellular data, the app wakes up its sync service.</p>
<p>This brings us to the mechanics of flutter background sync. You don’t want your sync process to only run when the app is actively open on the screen. Users frequently background apps to check a text or answer a call. By using background task managers (like <code>workmanager</code> or <code>flutter_background</code>), you can schedule periodic uploads or trigger sync events even when the app is resting in the background.</p>
<p>But what happens if the device is online, but your backend server is temporarily down or rejecting requests due to rate limits? This is where retry logic becomes essential.</p>
<p>You should never just try once, fail, and delete the queued item. Instead, implement an exponential backoff strategy. If the first API sync fails, the app waits two seconds and tries again. If that fails, it waits four seconds, then eight, and so on. This prevents your app from aggressively hammering a struggling server while ensuring the data eventually makes its way home.</p>
<h2>The Elephant in the Room: Offline First Conflict Resolution</h2>
<p>We’ve covered saving data locally and shipping it off to the server. But here is where things get truly complicated. What happens when two different sources change the same piece of data at the same time?</p>
<p>Imagine this scenario: A user is on a flight without Wi-Fi. They open your app and edit a document. Meanwhile, their colleague on the ground opens the web dashboard and edits that exact same document. When the plane lands and the mobile app finally reconnects, you have two conflicting versions of reality. The browser has its own storage and sync constraints for this same problem, which we cover in <a href="https://stacklynlabs.com/blog/the-architecture-of-local-first-web-development/">the architecture of local-first web development</a>.</p>
<p>This is the core challenge of offline data synchronization. If you blindly overwrite the server's data with the app's data, the colleague's work is destroyed. To prevent data loss, you need a deliberate offline first conflict resolution strategy.</p>
<h3>Strategy 1: Last-Write-Wins (LWW)</h3>
<p>The most common and straightforward approach is Last-Write-Wins. In this model, every single record (and ideally, every single field) is stamped with a precise timestamp when it is modified.</p>
<p>When a conflict occurs during a sync, the server simply compares the timestamps. The edit with the most recent timestamp is accepted, and the older edit is discarded. It’s deterministic, easy to understand, and works perfectly for apps where a single user is syncing their own data across multiple personal devices.</p>
<h3>Strategy 2: Field-Level Merging</h3>
<p>If Last-Write-Wins is too destructive for your use case, you can step up to custom field-level merging. Instead of looking at the document as a whole, the system evaluates conflicts field by field. If User A changed the title of the document, and User B changed the description, the server can safely merge both changes together into a single, cohesive document because the specific fields don't overlap.</p>
<h3>Strategy 3: Delta Syncs</h3>
<p>To optimize this whole process and save bandwidth, you should implement Delta Syncs. Rather than downloading the entire database every time the app reconnects, the mobile client simply tells the server, "Here is the timestamp of my last successful sync." The server then responds only with the specific records that have changed since that exact moment. This keeps API payloads incredibly small and makes the sync process feel instantaneous.</p>
<p>Wiring all of this yourself (the sync queue, the retry logic, the conflict resolution) is a lot of engineering before you write a single user-facing feature, and it only works if the local layer underneath is solid. <a href="https://stacklynlabs.com/product/stockpilot/">StockPilot</a> gives you that single-device layer already built: an encrypted Hive CE store, a checkout that cannot record a sale twice, and validated backup and restore. It does not sync between devices, so the queue and conflict rules above are what you would add on top. For a point-of-sale app specifically, our guide to <a href="https://stacklynlabs.com/blog/offline-pos-architecture-flutter/">designing an offline POS with an outbox and per-till receipt numbers</a> walks through that design.</p>
<h2>Putting It All Together</h2>
<p>Building a truly offline-first application requires a shift in how you think about architecture. You can no longer rely on the server to hold your hand through every single interaction. The mobile client must be smart, resilient, and capable of managing its own state.</p>
<p>By combining an optimistic UI for immediate visual feedback, local Hive storage for durable queuing, intelligent background retry logic, and robust conflict resolution strategies, you can build apps that feel unbreakable. Your users might not know what "Last-Write-Wins" means, but they will definitely notice when your app is the only one on their phone that still works flawlessly in a subway tunnel.</p>
<p><strong>Need help building resilient mobile applications?</strong></p>
<p>At Stacklyn Labs, we design and develop high-performance, cross-platform mobile apps that handle complex edge cases seamlessly. Whether you're dealing with tricky offline data synchronization, custom web implementations, or building a scalable backend architecture, our team is ready to bring your vision to life. Reach out to us today, and let’s build something bulletproof together.</p>
<h2>References &amp; Further Reading</h2>
<ul>
<li>DeCandia, G., Hastorun, D., Jampani, M., et al. (2007). Dynamo: Amazon's Highly Available Key-value Store. <em>ACM SIGOPS Operating Systems Review</em></li>
<li>Denko, M. K., &amp; Lu, H. (2006). Replica Dissemination and Update Strategies in Cluster‐Based Mobile Ad Hoc Networks. <em>Mobile Information Systems</em></li>
<li>Iovescu, D., &amp; Tudose, C. (2024). Real-Time Document Collaboration System Architecture and Design. <em>Applied Sciences</em></li>
<li>Preguiça, N., Baquero, C., &amp; Shapiro, M. (2022). Conflict-Free Replicated Data Types (CRDTs). <em>Encyclopedia of Big Data Technologies</em></li>
<li>Saito, Y., &amp; Shapiro, M. (2005). Optimistic replication. <em>ACM Computing Surveys</em></li>
</ul>
<hr />
<p><em>Further reading: <a href="https://stacklynlabs.com/guides/offline-first-business-apps/">Offline-first business apps: the guide</a></em></p>
]]></content:encoded></item><item><title><![CDATA[App Store 4.2.6 Template Rejection: 4.2.6 vs 4.3 Explained]]></title><description><![CDATA[A 4.2.6 or 4.3 rejection on a reskinned template app: what each rule targets, how to fix it, and how to reply or appeal.]]></description><link>https://stacklynlabs.hashnode.dev/app-store-4-2-6-template-rejection</link><guid isPermaLink="true">https://stacklynlabs.hashnode.dev/app-store-4-2-6-template-rejection</guid><category><![CDATA[iOS]]></category><category><![CDATA[app store]]></category><category><![CDATA[Flutter]]></category><category><![CDATA[Mobile Development]]></category><category><![CDATA[Apple]]></category><dc:creator><![CDATA[Stacklyn Labs]]></dc:creator><pubDate>Fri, 13 Nov 2026 04:32:38 GMT</pubDate><content:encoded><![CDATA[<p><em>Originally published on <a href="https://stacklynlabs.com/blog/app-store-4-2-6-template-rejection/">Stacklyn Labs</a>.</em></p>
<p>The email from App Review arrives a day or two after you press submit. Your app, the one you bought as Flutter source code and paid someone to rebrand, did not pass. The message cites guideline 4.2.6, or 4.3, or both, with a paragraph of Apple's wording that seems to describe somebody else's business.</p>
<p>In a way it does. Most pages that rank for an <strong>App Store 4.2.6 template rejection</strong> were written for app-builder platforms that publish apps on behalf of their customers, or lately for AI-generated apps. This post is for a different case: you bought template source code from a marketplace such as CodeCanyon or Codester, it was reskinned, and now you need to know whether the app is dead or fixable.</p>
<p>Often it is fixable. The fix depends on which rule you were cited under, and many guides blur them together. Guideline 4.2.6 is about who submits the app. Guideline 4.3(a) is about shipping many copies of one app. Guideline 4.3(b) is about an app that looks like what is already on the store. Three rules, three causes, three fixes. None of the fixes below guarantees approval, because Apple decides, but each one removes a specific reason for rejection.</p>
<p>Template rules sit alongside the design, privacy and metadata problems covered in our guide to <a href="https://stacklynlabs.com/blog/how-to-pass-app-store-review-avoiding-common-ui-ux-rejections/">passing App Store review</a>. This post stays on the three rules that catch template apps.</p>
<h2>App Store 4.2.6 template rejection: what the rule says</h2>
<p>Guideline 4.2.6 sits under 4.2, Minimum Functionality, which asks that an app be useful, unique or app-like rather than a repackaged website. The rule itself, in Apple's <a href="https://developer.apple.com/app-store/review/guidelines/">App Store Review Guidelines</a>, says apps created from a commercialized template or app generation service will be rejected "unless they are submitted directly by the provider of the app's content."</p>
<p>Two more sentences follow. Template and app generation services should not submit apps on behalf of their clients, and should give those clients tools to build customised, innovative apps instead. Template providers also get one other accepted route: a single binary that hosts every client's content in an aggregated or picker model. Apple's examples are a restaurant finder with a page for each client restaurant, and an event app with an entry for each client event.</p>
<p>The history explains the wording. The earlier version of the rule rejected template-built apps outright. As <a href="https://techcrunch.com/2017/12/20/apple-revises-its-controversial-guidelines-on-template-based-apps/">TechCrunch reported on 20 December 2017</a>, Apple revised it after the ban caught small businesses, restaurants, nonprofits and clubs that lacked the money or skills for a custom app, and added the exception for apps submitted by the content provider. The target was services uploading apps for their clients.</p>
<p>Here is the awkward part. The guideline does not define what counts as a commercialized template, and nothing in it exempts source code you bought and customised. A reviewer looking at a reskinned app can cite 4.2.6, and we cannot tell you how a given reviewer will read it. Arguing about what the rule was originally for is a weak position. Meeting the condition it actually sets is a strong one.</p>
<p>Guideline 5.2.1 points the same way. Apps should be submitted by the person or legal entity that owns or has licensed the intellectual property and other relevant rights. For a template buyer, that is you: your template licence gives you the right to use the code, and the content you add is yours. If you are unsure your licence fits the app you plan to ship, settle <a href="https://stacklynlabs.com/blog/codecanyon-regular-vs-extended-license-flutter-apps/">the Regular vs Extended licence question</a> before you submit.</p>
<p>In practice, 4.2.6 comes down to two things a template buyer controls:</p>
<ul>
<li><strong>The submitting account is yours.</strong> The app goes to App Review from your own Apple Developer account, not from the account of the freelancer, agency or template seller who did the reskin.</li>
<li><strong>The seller name is yours.</strong> The name shown under the app on the App Store is your legal name or your company's.</li>
</ul>
<p>If someone else uploaded your app from their account, start there. Submitting from your own account is the fix that matches what the rule asks for.</p>
<h3>Individual or organization developer account</h3>
<p>Apple's <a href="https://developer.apple.com/programs/enroll/">enrolment page</a> sets out what that seller name will be. Enrol as an individual and your legal name is shown as the seller. Enrol as an organization and the organization's legal name is shown. An organization also needs:</p>
<ul>
<li>a D-U-N-S Number</li>
<li>to be a legal entity; Apple does not accept DBAs, trade names or branches</li>
<li>a public website on its own domain</li>
<li>an enrolling person with the authority to bind the organization</li>
</ul>
<p>Either way, membership costs $99 per membership year, and local prices vary. If you want a company name under the app rather than your own, sort out the organization requirements before the build is ready, not after the rejection.</p>
<h2>Guideline 4.3(a) and 4.3(b) are different problems</h2>
<p>Guideline 4.3 is titled Spam. Its two parts catch template apps for different reasons: one for having too many copies, the other for being too much like everything else.</p>
<table>
<thead>
<tr>
<th>Rule</th>
<th>What it is really about</th>
<th>Typical trigger for a template buyer</th>
<th>Fix</th>
</tr>
</thead>
<tbody><tr>
<td>4.2.6</td>
<td>Who submits</td>
<td>A freelancer, agency or template seller uploads the app from their own account</td>
<td>Submit from the account of whoever provides the app's content: yours</td>
</tr>
<tr>
<td>4.3(a)</td>
<td>Same app, many bundle IDs</td>
<td>Several near-identical branded copies of one template, one per city, client or gym</td>
<td>One app with the variations inside it; Apple suggests in-app purchase for versions</td>
</tr>
<tr>
<td>4.3(b)</td>
<td>Indistinguishable from what exists</td>
<td>A rebrand that changes only the logo and colours, still on demo data, in a crowded category</td>
<td>Real content, real data and a real use case that make it meaningfully different</td>
</tr>
</tbody></table>
<p>4.3(a) catches the founder or agency with a plan: one template, sold as a branded app to every gym, salon or city. Apple's own example is a separate map app for every city instead of one map app that lets users search any city. Its suggested alternative for location or team versions is a single app with the variations provided through in-app purchase. If your business model is many copies of one binary, that is a product decision to revisit, not something a metadata change will fix.</p>
<p>4.3(b) catches the single app that looks like what is already there. Apple gives examples it calls well established: dating, flashlight, sound effects, wallpaper, simple timers and fortune telling. It will not accept new submissions in those unless they offer a meaningfully different or improved experience. Sound effects is on that list, so a reskinned sleep-sounds or white-noise template starts in a category where Apple has already raised the bar.</p>
<p>The same guideline calls some kinds of app low-effort, naming drinking games and fart and burp apps among them, and says repeated submissions of that kind may lead to removal from the Apple Developer Program. That warning is about low-effort apps, not reskins as such, but it is one more reason not to resubmit an unchanged build.</p>
<p>If you have not submitted yet, most of what guards against these rejections is decided before anyone touches the code. Our <a href="https://stacklynlabs.com/help-article/reskin-checklist-before-you-start/">checklist to work through before you reskin</a> puts the accounts, bundle ID and demo content decisions in order.</p>
<h2>What the 4.3 rejection message is telling you</h2>
<p>Apple does not publish its rejection notices, but developers paste them into Apple's Developer Forums. Two of them, <a href="https://developer.apple.com/forums/thread/825522">posted in May 2026</a> and <a href="https://developer.apple.com/forums/thread/757046">in June 2024</a>, are both labelled Guideline 4.3(a) - Design - Spam.</p>
<ul>
<li><strong>"a similar binary, metadata, and/or concept"</strong> names three separate tests. The binary is the compiled app. Metadata is the name, description and screenshots. Concept is what the app is for. Any one can be enough, and a new theme changes none of them much.</li>
<li><strong>Compared with whom.</strong> The May 2026 notice compares the app with apps from other developers that differ only slightly. The 2024 one compares it with apps from a developer account Apple had terminated. Either way, other buyers of your template count against you. That is how a 4.3(a) citation reaches a founder who has submitted one app, even though the guideline's text is about one developer's many Bundle IDs.</li>
<li><strong>Next Steps.</strong> Both ask the developer to review the app concept and submit a unique app with distinct content and functionality. Design is not in that list.</li>
<li><strong>Resources.</strong> The May 2026 notice lists contributing factors, including the same source code or assets as apps already submitted, and buying a template with problematic code from a third party. Apple does not define problematic, and we will not guess.</li>
</ul>
<p>We have not found a recent 4.2.6 notice posted in full, so we do not paraphrase one here.</p>
<h2>Where guideline 4.1 Copycats overlaps</h2>
<p>Guideline 4.1(a) asks you not to make minor changes to another app's name or UI and pass it off as your own. 4.1(c) says you cannot use another developer's icon, brand or product name in your app's icon or name without their approval. Roughly, 4.1 is about resembling one app and 4.3 about resembling many.</p>
<p>For a template buyer, that other developer is often the template author. Their product name is the template's name, and their branding can sit in the default icon, the splash screen and the About page. Strip all of it from your app name, icon and metadata. Apple's <a href="https://developer.apple.com/help/app-review/guideline-reference/4-1-prevent-copycat-rejection">help page on copycat rejections</a> also asks you to keep your developer name and Support URL accurate, so a support link that still points at the author's site works against you twice.</p>
<h2>Why a new logo and colours still gets 4.3(b)</h2>
<p>Look at the app from the reviewer's side. Suppose they open it and find three sample customers with made-up names, placeholder text in a notes field, and screenshots that match the template's marketplace listing. The app name is the template's name with one word changed. Nothing in it shows a real business built it for real users.</p>
<p>The usual giveaways in a template rebrand:</p>
<ul>
<li><strong>Demo data and placeholder text</strong> still in the app: sample records, lorem ipsum, the author's support email or links.</li>
<li><strong>Template screenshots</strong>, or screenshots of only the splash and login screens. Guideline 2.3.3 asks for screenshots that show the app in use.</li>
<li><strong>A name, icon style and description</strong> that read as a variation on the template's listing.</li>
<li><strong>Features nobody uses</strong>, left visible because removing them was more work than leaving them.</li>
</ul>
<p>What moves an app away from 4.3(b) is content and purpose: your data, your business's real use case, and screens that show it doing something specific for a specific audience. Colours cannot do that on their own. Neither can a new icon.</p>
<p>Doing this properly reaches well past the theme file. The content, the assets, the bundle ID and package name, the signing setup, the Firebase registration if the template uses it, and the store metadata all have to change together. If you have not done it before, that is several days of work, and the usual way to find a mistake is a failed build or a second rejection. If you would rather hand that list over, we do <a href="https://stacklynlabs.com/services/app-reskinning/">a reskin that removes the usual template rejection triggers</a>. We cannot promise approval. Nobody honestly can.</p>
<p>If a bundle ID or signing step has already gone wrong, our guide to <a href="https://stacklynlabs.com/blog/flutter-package-name-app-signing/">Flutter package name and app signing mistakes</a> covers what can and cannot be undone.</p>
<h2>What meaningfully different looks like</h2>
<p>Apple publishes no threshold for 4.3(b), so judge your app by what a reviewer can see when they open it.</p>
<table>
<thead>
<tr>
<th>What the reviewer sees</th>
<th>Reskin only</th>
<th>Meaningfully different</th>
</tr>
</thead>
<tbody><tr>
<td>App name</td>
<td>The template's name with a word changed</td>
<td>Your business or product name</td>
</tr>
<tr>
<td>First launch</td>
<td>Sample records and demo customers</td>
<td>Your real data, or an empty start with onboarding written for your users</td>
</tr>
<tr>
<td>Content</td>
<td>The images, text or audio every buyer received</td>
<td>Content you made or licensed for this app</td>
</tr>
<tr>
<td>Features</td>
<td>Every template screen, used or not</td>
<td>The screens your users need, plus something the template did not have</td>
</tr>
<tr>
<td>Audience</td>
<td>"For salons", or for everyone</td>
<td>One named audience with one job to do</td>
</tr>
<tr>
<td>Screenshots</td>
<td>The marketplace listing images</td>
<td>Your app in use with your content (2.3.3)</td>
</tr>
</tbody></table>
<p>Two buyers of one salon booking template show the difference. One changes the colours and keeps the stock service list. The other runs a salon, and its app lists that salon's own services, prices, stylists and opening hours. Only the second gives a reviewer something to tell it apart from other copies, and even that is not a guarantee.</p>
<p>Content is where templates are thinnest, because every buyer gets the same assets. Our <a href="https://stacklynlabs.com/product/zenith/">sleep sounds template with a JSON audio catalogue</a> is an honest example: its 45 copyright-free tracks ship with every copy, in the sound effects territory 4.3(b) names. Its sounds, moods and radio tracks are listed in JSON files, and the audio URLs can point at your own server, so swapping in audio you own is a content edit and a rebuild, with no Dart changes. Sourcing that audio is still your job.</p>
<h2>After a rejection: reply, fix, resubmit or appeal</h2>
<p>Rejections arrive with details in App Store Connect, including the specific guidelines the submission did not follow. Work through it in this order.</p>
<ol>
<li><strong>Read the exact guideline cited.</strong> A 4.2.6 citation is about the account and who submitted. A 4.3(a) citation is about copies. A 4.3(b) citation is about how distinct the app is. Fixing the wrong one costs you a review cycle.</li>
<li><strong>Reply in App Store Connect.</strong> Open the App Review section on the app's page. Apple says you can correspond with App Review there to resolve issues before resubmitting, so ask if the message is unclear about what triggered it. That reply field is not for appeals, which have their own form.</li>
<li><strong>Make the real change, then resubmit.</strong> Submit from your own account, fold the copies into one app, or replace the demo content and screenshots with your own. A cosmetic tweak to the same build is likely to get the same answer.</li>
<li><strong>Appeal only if App Review misunderstood the app.</strong> Apple's <a href="https://developer.apple.com/distribute/app-review/">App Review page</a> allows an appeal to the App Review Board if you believe Apple misunderstood your app or treated you unfairly. Give specific reasons the app complies with the guidelines, file one appeal per rejected submission, and answer any requests for more information first. If the app genuinely matches what the rejection describes, change the app instead.</li>
</ol>
<p>Apple says it typically reviews at least 50% of submissions in under 24 hours and 90% in under 48, so the waiting is rarely the slow part. Working out what to change is.</p>
<h3>How long each route takes</h3>
<ul>
<li><strong>Reply.</strong> A specialist familiar with your app answers in App Store Connect, according to Apple's <a href="https://developer.apple.com/help/app-review/after-submitting-for-review/contact-app-review">help page on contacting App Review</a>. You can request a call from the same message window, and Apple says calls are typically completed within three to five business days.</li>
<li><strong>Resubmission.</strong> The build goes back into the queue. The guidelines warn that an app repeatedly rejected for the same violation will take longer to review, so a cosmetic resubmission gets the same answer more slowly.</li>
<li><strong>Appeal.</strong> The App Review Board replies in App Store Connect and may ask for more information or a call. Apple publishes no turnaround time. One developer on its forums reported <a href="https://developer.apple.com/forums/thread/836514">12 days with no reply</a> to a 4.3(a) appeal in June 2026.</li>
</ul>
<p>Pick one route. Apple's <a href="https://developer.apple.com/help/app-review/after-submitting-for-review/appeal-to-the-app-review-board">appeal help page</a> asks for one appeal per rejected app covering every cited issue, and none after you have already fixed the issues and resubmitted.</p>
<h3>What to put in your reply</h3>
<p>There is no magic wording, and a reply copied from a forum reads like one. State facts. A useful reply covers four things:</p>
<pre><code class="language-text">1. Who you are: your name or company, matching the seller name on the account.
2. Ownership: you provide the app's content and submit it from your own
   developer account. The app is built on licensed template code, customised
   for [your purpose].
3. What makes it different: who it is for, what it does for them, and the
   real content it ships with.
4. What changed since the rejection: the specific items, such as sample data
   removed, screenshots replaced, or submission moved to your own account.
</code></pre>
<p>Keep it short. If one of those lines is hard to write honestly, that line is the thing to fix before you reply.</p>
<h2>Frequently asked questions</h2>
<h3>Can I publish an app built from a CodeCanyon or Codester template?</h3>
<p>Yes. Nothing in the guidelines bans template code as such: 4.2.6 asks that the provider of the app's content submits it, and 4.3 asks that it not copy what is already there. Your own account, your own content and a real use case cover both.</p>
<h3>Does changing the design fix a 4.3 rejection?</h3>
<p>Not on its own. The notices developers post judge similarity by binary, metadata and concept, and ask for distinct content and functionality. A new colour scheme changes none of those much, so change what the app contains and who it serves first.</p>
<h3>How long does an App Review Board appeal take?</h3>
<p>Apple publishes no turnaround time. The Board replies in App Store Connect and may ask for more information or arrange a call, and one developer on Apple's forums reported 12 days without a reply.</p>
<h3>Can my developer or agency submit the app for me?</h3>
<p>They can do the work inside your account. In App Store Connect the account holder can invite people under Users and Access and choose their roles, while the app stays under your account and seller name. In our reading of 4.2.6, that is the part that counts. An upload from their own account is what fails.</p>
<h3>My live app's update was rejected under 4.3. What now?</h3>
<p>An approved earlier version does not protect the next submission. Check the top of the rejection message for a Bug Fix Submissions note. If it is there, you can reply asking for this update to be approved and fix the issues in your next one, without resubmitting in the meantime. If it is not, the update has to meet the guideline before it goes out.</p>
<h3>Can a 4.3 rejection get my developer account removed?</h3>
<p>Nothing in the guidelines says one 4.3 rejection does. Two lines do carry account risk: 4.3(b) warns that repeated submissions of low-effort apps may lead to removal from the Apple Developer Program, and 4.1(b) says the same of apps that impersonate others.</p>
<h2>Pre-submission checklist for template apps</h2>
<p>Run through this before the first submission, or before you resubmit after a rejection. Most items map to a guideline covered above, so a no on any line tells you what to fix.</p>
<ul>
<li><strong>Your own Apple Developer account</strong>, as an individual or an organization, not your developer's.</li>
<li><strong>Your seller name</strong>: your legal name or your company's, as you want customers to see it.</li>
<li><strong>A bundle ID of your own</strong>, unique to this app and free of the template author's name, set before the first upload.</li>
<li><strong>One app, not a copy per client or location.</strong> If you need versions, plan them inside a single app (4.3(a)).</li>
<li><strong>Demo content gone</strong>: sample records, placeholder text, the author's links and support details.</li>
<li><strong>Screenshots of the app in use</strong> with your own content, not the template's images or only the splash and login screens (2.3.3).</li>
<li><strong>A name, icon and description that are yours</strong>, not a variation on the template's listing.</li>
<li><strong>An equivalent login option if you use social login.</strong> If Google, Facebook or another third-party login sets up the user's main account, guideline 4.8 requires another login option that limits data collection to name and email, lets users keep their email private, and does not collect interactions for advertising without consent. The current text describes those features rather than naming Sign in with Apple. Apple lists exceptions, such as apps that use only the company's own account system.</li>
</ul>
<p>Getting all of that right on an account in your own name, plus the privacy forms and review notes, is where most first submissions stall. If you would rather hand that part over, our <a href="https://stacklynlabs.com/services/app-store-deployment/">App Store submission service for Flutter apps</a> uploads your signed build, fills in the listing and forms, and submits it from your account.</p>
<p>If you are holding a rejection and are not sure which rule applies or what to change, <a href="https://stacklynlabs.com/hire-us/">talk to us about your rejection</a> and include the exact wording from App Store Connect. If the honest answer turns out to be a proper rebrand, <a href="https://stacklynlabs.com/blog/app-reskinning-cost/">what a proper reskin costs</a> lays out the work items and the fees that sit outside any quote.</p>
<hr />
<p><em>Further reading: <a href="https://stacklynlabs.com/guides/buying-flutter-app-templates/">Buying Flutter app templates: the guide</a></em></p>
]]></content:encoded></item><item><title><![CDATA[Flutter Package Name Change and App Signing: Fixing Mistakes]]></title><description><![CDATA[Wrong package name already live, lost keystore, Google Sign-In broken after the ID change? What Play and the App Store let you recover.]]></description><link>https://stacklynlabs.hashnode.dev/flutter-package-name-app-signing</link><guid isPermaLink="true">https://stacklynlabs.hashnode.dev/flutter-package-name-app-signing</guid><category><![CDATA[Flutter]]></category><category><![CDATA[Android]]></category><category><![CDATA[iOS]]></category><category><![CDATA[Firebase]]></category><category><![CDATA[Mobile Development]]></category><dc:creator><![CDATA[Stacklyn Labs]]></dc:creator><pubDate>Wed, 11 Nov 2026 02:16:57 GMT</pubDate><content:encoded><![CDATA[<p><em>Originally published on <a href="https://stacklynlabs.com/blog/flutter-package-name-app-signing/">Stacklyn Labs</a>.</em></p>
<p>You are halfway through rebranding a Flutter template. The new logo is in, the colours are yours, and then something goes wrong that no tutorial warned you about. Play Console rejects the upload. Google Sign-In fails with an error code and no explanation. Or you notice the build you shipped last month still carries <code>com.example</code>, or the template author's ID, and the keystore that signed it is on a laptop you no longer have.</p>
<p>Most guides on how to change the package name and set up app signing in Flutter assume you are starting clean. This one is for when you are not. It covers the mistakes that most often stop a reskin halfway, what each one costs, and which ones can be undone. Some cannot, and it is better to know that now than after another week of trying.</p>
<p>These mistakes also compound. A leftover author ID or demo content does not only break builds. It is the kind of thing App Review notices under the <a href="https://stacklynlabs.com/blog/app-store-4-2-6-template-rejection/">App Store 4.2.6 template rejection rules</a>, which also expect the app to come from your own developer account, not the seller's. Fixing identity and passing review are largely the same job.</p>
<p>We will not repeat the step-by-step rename or the first signed build here. Both are in our Help Center and linked below. This post is about recovery.</p>
<h2>Work out which mistake you have</h2>
<p>Match the symptom to the cause before changing anything. Half the time people fix the wrong layer.</p>
<table>
<thead>
<tr>
<th>Symptom</th>
<th>Likely cause</th>
<th>Recoverable?</th>
</tr>
</thead>
<tbody><tr>
<td>Play Console refuses the upload because of the package name</td>
<td><code>com.example</code> left in <code>applicationId</code>, or an ID already taken</td>
<td>Yes, if nothing is published</td>
</tr>
<tr>
<td>App is live under the wrong ID</td>
<td>ID changed too late, or never changed</td>
<td>Not in place</td>
</tr>
<tr>
<td>Play says the bundle is signed with the wrong key</td>
<td>A different upload keystore from the one Play has on record</td>
<td>Yes, with Play App Signing</td>
</tr>
<tr>
<td>Keystore or its passwords are gone</td>
<td>No backup</td>
<td>Yes with Play App Signing; no if you held the signing key yourself</td>
</tr>
<tr>
<td>Google Sign-In fails with error 10, Maps shows a grey grid, Firebase goes quiet</td>
<td>New ID or key not registered with Google's services</td>
<td>Yes</td>
</tr>
<tr>
<td>Xcode reports a provisioning or signing error</td>
<td>Bundle ID, App ID, profile and certificate disagree</td>
<td>Yes</td>
</tr>
</tbody></table>
<h2>You published with the wrong package name or bundle ID</h2>
<p>Start with the honest answer. Android's documentation says that once you publish, you should never change the application ID, because <a href="https://developer.android.com/build/configure-app-module">Google Play treats the upload as a completely different app</a>. App Store Connect says the bundle ID <a href="https://developer.apple.com/help/app-store-connect/reference/app-information/app-information">can't be changed after you upload a build</a>. No setting or support ticket renames a live app. You have three options.</p>
<p><strong>Live with it.</strong> Users rarely see the ID; it shows in the Play Store URL and in device settings. If it is merely ugly, keeping it costs nothing. If it is the template author's own ID, think harder, because you have shipped someone else's name inside your app.</p>
<p><strong>Publish a new app under the right ID.</strong> You start again at zero installs, ratings and reviews, and existing users get no updates from the new listing. The old ID is not freed either: Google's page on <a href="https://support.google.com/googleplay/android-developer/answer/9023647">deleting an app</a> says a package name with any lifetime installs can never be reused, even by your own account. Apple will not let you <a href="https://developer.apple.com/help/account/manage-identifiers/delete-an-app-id">delete an explicit App ID</a> once an app using it has been uploaded to App Store Connect.</p>
<p><strong>Transfer, if the real problem is the account.</strong> A common version of this mistake: a freelancer or the seller published the app from their own developer account. The ID may be fine; it is just in the wrong place. Play's <a href="https://support.google.com/googleplay/android-developer/answer/6230247">app transfer</a> is requested from the original account and approved by yours, and carries over users, ratings and reviews. Apple's <a href="https://developer.apple.com/help/app-store-connect/transfer-an-app/overview-of-app-transfer">app transfer</a> is started by the original Account Holder and keeps the bundle ID, ratings and reviews. Both need the other party's cooperation. Who owns the accounts and the keys is one of the questions to settle before you pay anyone, and it is one of the line items that separate a cheap quote from a complete one in our breakdown of <a href="https://stacklynlabs.com/blog/app-reskinning-cost/">app reskinning cost for a template you bought</a>.</p>
<h2>Leftover com.example or the original author's ID</h2>
<p><code>com.example</code> is the ID <code>flutter create</code> generates, and it survives in more templates than you would expect. Play Console refuses it. The error is widely reported as "com.example is restricted", though we could not find that wording in Google's own help pages. Some authors swap in their own ID instead, which is worse: if they have published under it, Play will not accept it from you, and if they have not, you are about to make their ID permanent in your app.</p>
<p>The <code>applicationId</code> is rarely the only copy. Templates hide the old ID in Kotlin folder paths, a manifest <code>package</code> attribute, deep-link hosts, method channel names, ProGuard rules, Firebase config files and the iOS test target. Search the whole project for the old string before you build anything you intend to upload.</p>
<h2>You lost the keystore, or the passwords</h2>
<p>First work out which key you lost. Android apps on Play have two. The <strong>upload key</strong> signs the bundle you send to Google. The <strong>app signing key</strong> signs what users download, and with Play App Signing, Google holds it.</p>
<p>Since August 2021, <a href="https://developer.android.com/guide/app-bundle">new apps must publish as an Android App Bundle</a>, and Google's help page says apps uploading bundles are enrolled in Play App Signing by default. So if your app went live recently as an <code>.aab</code>, the key you lost is almost certainly the upload key, and Google says plainly that <a href="https://support.google.com/googleplay/android-developer/answer/9842756">you are not locked out of your app</a>. The recovery is an upload key reset:</p>
<ol>
<li>Create a new upload keystore, exactly as in <a href="https://stacklynlabs.com/help-article/first-build-and-signing/">creating your upload keystore and first signed release</a>.</li>
<li>Export its certificate to a <code>.pem</code> file with <code>keytool</code>.</li>
<li>In Play Console, open the app's Play App Signing page, choose <strong>Request upload key reset</strong>, give a reason and upload the <code>.pem</code> file.</li>
</ol>
<p>You need admin permission to configure Play App Signing. Google does not say how long a reset takes and forum reports vary, so do not promise anyone a release date until it is approved. The page also moves between menus; on 26 October 2026 Google's help puts it under <strong>Protected with Play</strong>.</p>
<p>The other case is worse. If you managed the app signing key yourself, which was possible for apps first published as APKs, Google's page is direct: that key cannot be reset if you lose it. The app can no longer be updated, and you are back to a new listing under a new ID. Lost passwords count as a lost key, because there is no supported way to recover a keystore password.</p>
<p>Add it up. A rename across Gradle, Kotlin folders and Xcode, a keystore that has to outlive your laptop, and then every Google service re-registered against the new ID and keys, as the next section shows. For a first-timer that is several evenings at best, and the one mistake that reaches the store cannot be undone. If you would rather not spend that week, <a href="https://stacklynlabs.com/services/app-reskinning/">we do this as part of reskinning</a>: package name and bundle ID, an upload keystore created and handed to you with its passwords, Android and iOS signing, Firebase and API keys re-registered, and store-ready builds, from $150 on the Pro tier.</p>
<h2>Firebase, Google Sign-In or Maps broke after the ID change</h2>
<p>This is the most confusing failure, because the app builds, installs and runs. Then sign-in fails, the map is a grey grid, or notifications stop. Google services identify an Android app by its package name and the SHA fingerprint of the certificate that signed it. Change either and the registration no longer matches.</p>
<h3>Firebase</h3>
<p>A Firebase Android app's package name <a href="https://firebase.google.com/docs/android/setup">cannot be changed after registration</a>, and neither can a <a href="https://firebase.google.com/docs/ios/setup">Firebase Apple app's bundle ID</a>. Register new Android and iOS apps under the new IDs, then run <code>flutterfire configure</code> again. A stale <code>google-services.json</code> gives a loud "No matching client found" build error. That is the easy case.</p>
<h3>The fingerprints you actually need</h3>
<p>The quiet failures come from fingerprints. Most people register one SHA-1, the debug key on their own machine, and stop. A store app has three keys:</p>
<table>
<thead>
<tr>
<th>Fingerprint</th>
<th>Signs</th>
<th>Where to get it</th>
</tr>
</thead>
<tbody><tr>
<td>Debug key</td>
<td>Builds you run from your IDE</td>
<td><code>./gradlew signingReport</code></td>
</tr>
<tr>
<td>Upload key</td>
<td>Release builds you install yourself</td>
<td><code>keytool -list -v</code> on your upload keystore</td>
</tr>
<tr>
<td>App signing key</td>
<td>What Play users download</td>
<td>Play Console, Play App Signing page</td>
</tr>
</tbody></table>
<p>Google's <a href="https://developers.google.com/android/guides/client-auth">client authentication guide</a> notes that under Play App Signing the upload certificate differs from the app signing certificate. Register only your debug SHA-1 and sign-in works on your phone and fails for everyone who installed from Play.</p>
<pre><code class="language-bash"># Upload key: prints SHA-1 and SHA-256
keytool -list -v -keystore /absolute/path/to/upload-keystore.jks -alias upload

# Debug and release variants Gradle knows about
cd android &amp;&amp; ./gradlew signingReport
</code></pre>
<p>Add them in Firebase under <strong>Project settings</strong>, in the SHA certificate fingerprints field of the new Android app. Some features want SHA-256: App Check's <a href="https://firebase.google.com/docs/app-check/android/play-integrity-provider">Play Integrity provider</a> asks for it, and phone authentication uses it for Play Integrity too. Add both hashes for each key and you will not have to come back. An upload key reset changes the upload fingerprint, so register the new one afterwards.</p>
<h3>Google Sign-In and Maps</h3>
<p>Google Sign-In on Android uses an OAuth client <a href="https://support.google.com/cloud/answer/15549257">created with the package name and SHA-1</a>. When those do not match the installed app, you get <code>ApiException: 10</code>, which Google's reference lists as <code>DEVELOPER_ERROR</code>: the app is misconfigured. It is not a bug in your Dart code, so do not go looking for one. On iOS the OAuth client is tied to the bundle ID, and the reversed client ID has to be in <code>Info.plist</code> as a URL scheme.</p>
<p>Maps keys fail the same way. Google's <a href="https://developers.google.com/maps/api-security-best-practices">API security guidance</a> restricts Android keys by package name plus SHA-1 and iOS keys by bundle ID, so a key restricted to the old ID rejects the renamed app.</p>
<h2>iOS bundle ID, provisioning profile and certificate mismatches</h2>
<p>iOS signing has three pieces that must agree. The App ID in your Apple Developer account must match the bundle ID in Xcode. The provisioning profile ties that App ID to a certificate; an App Store profile <a href="https://developer.apple.com/help/account/provisioning-profiles/create-an-app-store-provisioning-profile">contains a single distribution certificate</a>. And the certificate must be usable on the Mac doing the build.</p>
<p>Change the bundle ID and the old profile no longer applies. With automatic signing on and your team chosen under <strong>Signing &amp; Capabilities</strong>, Xcode creates what it needs once the new App ID exists. Most errors at this point have one of three causes: the App ID was never registered, the wrong team is selected (often the author's or a freelancer's), or a literal bundle ID is hard-coded somewhere Xcode does not update, such as <code>Info.plist</code> or the RunnerTests target.</p>
<p>Certificates cause a different panic. If your distribution certificate expired or was revoked, Apple says <a href="https://developer.apple.com/help/account/certificates/certificates-overview">apps already on the App Store are not affected</a> while your membership is valid. You cannot upload new builds signed with it, so create a new certificate and carry on. Unlike a self-managed Android key, nothing here locks you out of your own app.</p>
<h2>Change the Flutter package name and app signing in the right order</h2>
<p>If nothing is live yet, you are in the cheap part of this. Five checks catch most of the mistakes above:</p>
<ul>
<li><strong>The ID is final.</strong> Reverse domain, a name you own, no <code>com.example</code>, no author ID.</li>
<li><strong>The accounts are yours.</strong> Play Console and the Apple Developer Program, in your name or your company's.</li>
<li><strong>The keystore is backed up,</strong> with both passwords and the alias, somewhere you will still have in three years.</li>
<li><strong>Every Google service knows the new ID,</strong> with debug and upload fingerprints now and the app signing fingerprint as soon as Play shows it.</li>
<li><strong>A release build works on a real phone,</strong> including sign-in, maps and notifications.</li>
</ul>
<p>If you are already past one of these and stuck, send us the template, the ID you want to keep and what is failing, and we will tell you which of the options above you actually have: <a href="https://stacklynlabs.com/hire-us/?service=app_reskin">send your reskin brief for a fixed quote</a>. If nothing is live yet and you would rather do it yourself, the Help Center walks through <a href="https://stacklynlabs.com/help-article/changing-your-app-package-name/">renaming a Flutter app's package and bundle ID</a> one file at a time.</p>
<hr />
<p><em>Further reading: <a href="https://stacklynlabs.com/help-article/changing-your-app-package-name/">Changing your app package name (help article)</a></em></p>
]]></content:encoded></item><item><title><![CDATA[Hive vs. Isar vs. SQLite: Choosing a Flutter Local Database in 2026]]></title><description><![CDATA[Hive and Isar have stalled. hive_ce, isar_community, drift, ObjectBox and sqflite compared on maintenance, queries and encryption.]]></description><link>https://stacklynlabs.hashnode.dev/building-zero-latency-mobile-apps-hive-vs-isar-vs-sqlite-choosing-a-flutter-local-database-in-2026</link><guid isPermaLink="true">https://stacklynlabs.hashnode.dev/building-zero-latency-mobile-apps-hive-vs-isar-vs-sqlite-choosing-a-flutter-local-database-in-2026</guid><category><![CDATA[Flutter]]></category><category><![CDATA[Databases]]></category><category><![CDATA[Dart]]></category><category><![CDATA[SQLite]]></category><category><![CDATA[Mobile Development]]></category><dc:creator><![CDATA[Stacklyn Labs]]></dc:creator><pubDate>Tue, 10 Nov 2026 04:22:16 GMT</pubDate><content:encoded><![CDATA[<p><em>Originally published on <a href="https://stacklynlabs.com/blog/building-zero-latency-mobile-apps-hive-vs-isar-vs-sqlite-choosing-a-flutter-local-database-in-2026/">Stacklyn Labs</a>.</em></p>
<p>You open a Flutter project from 2023 to add one feature. <code>flutter pub upgrade</code> fails because the code generator you pinned back then will not resolve against the current analyzer. Or you start a fresh app, add <code>isar</code> because an older comparison post told you to, and then notice its last stable release on pub.dev is from April 2023.</p>
<p>That is the real choice in 2026. Picking a <strong>Flutter local database</strong> used to be a speed question: key-value lookups, indexed queries, or SQL. Speed still matters. But the first question now is simpler and more awkward: who is still shipping fixes for the package you are about to build your whole app on?</p>
<p>The two names most comparison posts lead with, Hive and Isar, have both stalled upstream. Neither is marked discontinued on pub.dev, and both still work in apps today. But as of October 2026 the original <code>hive</code> package has had no stable release since June 2022, and <code>isar</code> has had no stable release since April 2023. Both now have community forks that are shipping. This post covers which package is which, how the options compare once you filter for maintenance, and what moving off each one involves.</p>
<p>Why does this matter so much? In an offline-first app the local database is the source of truth, not a cache. Reads come from the device, writes land on the device first, and a background job syncs later. Our <a href="https://stacklynlabs.com/blog/building-zero-latency-mobile-apps-the-offline-first-architecture-blueprint/">offline-first architecture blueprint for Flutter apps</a> walks through the full pattern. The short version: every screen sits on top of this one dependency, so a stalled package becomes your problem the day a new Flutter, Dart or Xcode release stops it building.</p>
<h2>Maintenance status of every Flutter local database worth considering</h2>
<p>These are the packages people actually shortlist. Dates come from pub.dev and the projects' GitHub repositories, checked on October 2, 2026.</p>
<table>
<thead>
<tr>
<th>Package</th>
<th>Latest stable</th>
<th>Last stable release</th>
<th>Status</th>
<th>What to know</th>
</tr>
</thead>
<tbody><tr>
<td><code>hive</code></td>
<td>2.2.3</td>
<td>June 30, 2022</td>
<td>Stalled, not marked discontinued</td>
<td>A 4.0.0 prerelease dates from August 2023. Last repository commit August 2023.</td>
</tr>
<tr>
<td><code>hive_ce</code></td>
<td>2.20.1</td>
<td>September 27, 2026</td>
<td>Active community fork</td>
<td>Describes itself as a continuation of Hive v2. Requires Dart 3.4 or later.</td>
</tr>
<tr>
<td><code>isar</code></td>
<td>3.1.0+1</td>
<td>April 25, 2023</td>
<td>Stalled, not marked discontinued</td>
<td>The v4 prerelease is flagged as not production-ready. The most recent commit (June 2025) added a privacy manifest.</td>
</tr>
<tr>
<td><code>isar_community</code></td>
<td>3.3.2</td>
<td>March 23, 2026</td>
<td>Active, bug-fix focused</td>
<td>Fork of the Isar v3 line. Repository commits as recent as September 2026. Web is not listed as a platform.</td>
</tr>
<tr>
<td><code>isar_plus</code></td>
<td>1.3.9</td>
<td>August 4, 2026</td>
<td>Active, single maintainer</td>
<td>A divergent fork. Its changelog points to an SQLite-based core.</td>
</tr>
<tr>
<td><code>drift</code></td>
<td>2.35.1</td>
<td>September 30, 2026</td>
<td>Active</td>
<td>Flutter Favorite, MIT licensed, runs on Android, iOS, Linux, macOS, Windows and web.</td>
</tr>
<tr>
<td><code>objectbox</code></td>
<td>5.3.2</td>
<td>May 20, 2026</td>
<td>Active, commercial vendor</td>
<td>A 6.0.0 preview is in progress. No web target. Sync is a paid feature.</td>
</tr>
<tr>
<td><code>sqflite</code></td>
<td>2.4.4</td>
<td>September 2026</td>
<td>Maintained, slow-moving</td>
<td>Android, iOS and macOS. Desktop through <code>sqflite_common_ffi</code>. Web is experimental.</td>
</tr>
<tr>
<td><code>realm</code></td>
<td>20.2.0</td>
<td>September 24, 2025</td>
<td>Deprecated by MongoDB</td>
<td>MongoDB announced the deprecation of the Realm SDKs and Atlas Device Sync in September 2024. Version 20.0.0 removed sync.</td>
</tr>
</tbody></table>
<h3>Stalled is not the same as broken</h3>
<p>Stalled is the accurate word, and the distinction matters. Neither <code>hive</code> nor <code>isar</code> carries pub.dev's discontinued flag, and neither repository is archived. An app built on Hive 2.2.3 in 2022 still opens its boxes today.</p>
<p>The risk is not that your app stops working tomorrow. It is that the package stops keeping up with everything around it: new Dart versions, analyzer upgrades that break old code generators, new iOS privacy requirements, Android Gradle changes. When one of those breaks a stalled package, nobody upstream is going to fix it for you. We cannot tell you which release will be the one.</p>
<p>There is an awkward twist with Hive. Its own README still points readers to Isar if they need queries, multi-isolate support or relations. That advice made sense in 2022. In 2026 it sends you from one stalled project to another. The Isar README, for its part, is blunt about the newer line: "ISAR V4 IS NOT READY FOR PRODUCTION USE", and it tells production users to stay on version 3.</p>
<h2>Hive and hive_ce: key-value storage with very little ceremony</h2>
<p>Hive is a lightweight NoSQL store written in pure Dart. Data lives in boxes, and you read and write by key. Because there are no native dependencies, it runs on mobile, desktop and the web without platform setup.</p>
<p>That model fits a lot of offline-first work. A settings box, a box per record type, and a dedicated box acting as a pending sync queue: when the user loses signal, their actions stack up in the queue box, and a background worker drains it when they reconnect. This is also why a small app can ship with no server bill at all, which we cover in <a href="https://stacklynlabs.com/blog/zero-backend-costs-running-a-solopreneur-app-on-local-databases/">running a solopreneur app on local databases with zero backend costs</a>.</p>
<p>What Hive does well:</p>
<ul>
<li><strong>Fast reads by key.</strong> A regular Hive box keeps its values in memory once it is open, so a read by key does not touch disk. A <code>LazyBox</code> keeps only keys in memory and reads values from disk, which trades speed for memory.</li>
<li><strong>Low setup cost.</strong> Initialize, open a box, read and write. For primitive values and maps there is nothing else to configure.</li>
<li><strong>Built-in encryption.</strong> The original Hive README states boxes are encrypted using AES-256. The <code>hive_ce</code> package page lists strong encryption as built in.</li>
</ul>
<p>What the older comparison posts skip:</p>
<ul>
<li><strong>Custom classes still need adapters.</strong> To store your own model objects you need a TypeAdapter per class, usually generated with <code>build_runner</code>. It is less ceremony than a SQL schema, but it is not zero.</li>
<li><strong>No query language.</strong> Filtering, sorting and joining mean loading records into Dart and using list methods. For settings, carts and small per-user datasets this is fine. For a large searchable catalog it becomes slow and memory-hungry, and you end up building indexes by hand.</li>
</ul>
<p><code>hive_ce</code> keeps the Hive v2 API and adds things the original never shipped: <code>IsolatedHive</code> for multi-isolate access, a DevTools inspector, automatic adapter generation, and Flutter web WASM support. Its README also claims large performance gains over Hive v4. Treat that as the maintainer's claim; we have not benchmarked it.</p>
<h2>Isar and its forks: indexed queries with an uncertain future</h2>
<p>Isar came from the same author as Hive and was meant to replace it. Instead of boxes, you define collections of objects with Dart annotations, and Isar generates the schema and query code. The feature list on the <code>isar_community</code> README is the same one that made Isar popular:</p>
<ul>
<li>Indexed queries with <code>and()</code>, <code>or()</code> and <code>xor()</code> groups</li>
<li>Full-text search</li>
<li>Watchers on collections, objects or queries, notified after a transaction commits</li>
<li>Asynchronous, parallel queries with multi-isolate support</li>
</ul>
<p>If you need every customer in one city with an overdue invoice, indexes are the difference between a query and a full scan. That is the job Isar was built for.</p>
<p>The costs are real. Code generation through <code>build_runner</code> is mandatory. And one claim from the earlier version of this post needs correcting: the Isar v3 line does not ship built-in encryption. Neither the original nor the <code>isar_community</code> README lists it. If you need data encrypted at rest with Isar, you are handling it yourself, field by field.</p>
<p>Then there is the maintenance question. If you choose Isar in 2026, you are really choosing between forks:</p>
<ul>
<li><strong><code>isar_community</code></strong> is the conservative choice. Its README says it focuses on bug fixes and small updates for version 3, so your existing Isar code keeps its API. Web is not in its platform list.</li>
<li><strong><code>isar_plus</code></strong> is more ambitious, with one maintainer. Its changelog suggests a move to an SQLite-based engine with web support. Treat it as a different database with a familiar API, not a drop-in v3 replacement.</li>
</ul>
<p>Either can be the right call. Both mean your storage layer depends on a small group of volunteers.</p>
<h2>SQLite through drift or sqflite: the relational option that is still moving</h2>
<p>SQLite is the filing cabinet: tables, rows, a declared schema. If your data is relational (customers, orders, invoices and line items that all reference each other) it is usually the safest model. In Flutter you reach it through <code>sqflite</code> (raw SQL) or <code>drift</code> (a type-safe layer with code generation).</p>
<p>What SQLite gives you:</p>
<ul>
<li><strong>Data integrity.</strong> Foreign keys and ACID transactions mean a delete that fails halfway rolls back instead of leaving orphaned rows.</li>
<li><strong>Joins and aggregates.</strong> One query can combine and total data across several tables.</li>
<li><strong>Maturity.</strong> SQLite itself has been in production use for decades, and both Flutter wrappers are still maintained.</li>
</ul>
<p>Drift is the strongest maintenance story on this list. It released 2.35.1 on September 30, 2026, is a Flutter Favorite, runs on all six Flutter platforms including web, and added FTS5 full-text search support in 2.35.0. Queries can be watched as streams, so the UI rebuilds when underlying rows change. For encryption, drift's documentation recommends SQLite3MultipleCiphers for new apps, with the <code>encrypted_drift</code> package (built on SQLCipher) as an alternative.</p>
<p><code>sqflite</code> is stable and widely used, but slow-moving. It does not support concurrent read and write transactions, and outside Android, iOS and macOS you need <code>sqflite_common_ffi</code>.</p>
<p>The catch with SQLite is upfront work. You plan the schema, write migrations every time it changes, and either hand-write SQL with <code>sqflite</code> or learn drift's table classes and DAOs. There is also a mapping step from rows to Dart objects on every read. For simple reads by ID, an in-memory Hive box will usually feel quicker. As the data grows and the questions get harder, that gap closes or reverses. Measure with your own data before deciding on speed alone.</p>
<h2>ObjectBox and Realm</h2>
<p><strong>ObjectBox</strong> is an object database from a commercial vendor. It is actively released, Apache-2.0 licensed, uses <code>build_runner</code> for code generation, and supports queries that filter across relations. It has no web target, and its sync product is a paid feature. If you want an object store with a company behind it and you only ship mobile and desktop, it belongs on the shortlist.</p>
<p><strong>Realm</strong> is the one to avoid for new work. MongoDB announced the deprecation of Atlas Device Sync and the Realm SDKs in September 2024. The Flutter SDK's 20.0.0 release, also from September 2024, removed all sync functionality, and the last release was in September 2025. If you are on Realm today, plan a migration rather than waiting.</p>
<h2>Feature comparison for the maintained options</h2>
<table>
<thead>
<tr>
<th></th>
<th><code>hive_ce</code></th>
<th><code>isar_community</code></th>
<th><code>drift</code></th>
<th><code>sqflite</code></th>
<th><code>objectbox</code></th>
</tr>
</thead>
<tbody><tr>
<td>Data model</td>
<td>Key-value boxes</td>
<td>Object collections</td>
<td>Relational tables</td>
<td>Relational tables</td>
<td>Objects with relations</td>
</tr>
<tr>
<td>Queries</td>
<td>By key; filter in Dart</td>
<td>Indexed queries, full-text search, watchers</td>
<td>Full SQL, joins, FTS5, stream queries</td>
<td>Raw SQL</td>
<td>Queries, including across relations</td>
</tr>
<tr>
<td>Encryption</td>
<td>Built in</td>
<td>Not built in</td>
<td>SQLite3MultipleCiphers or <code>encrypted_drift</code></td>
<td>Separate SQLCipher package</td>
<td>Check vendor docs</td>
</tr>
<tr>
<td>Web</td>
<td>Yes, including WASM</td>
<td>Not listed</td>
<td>Yes</td>
<td>Experimental</td>
<td>No</td>
</tr>
<tr>
<td>Code generation</td>
<td>For custom class adapters</td>
<td>Required</td>
<td>Required</td>
<td>None</td>
<td>Required</td>
</tr>
<tr>
<td>Setup cost</td>
<td>Lowest</td>
<td>Medium</td>
<td>Highest</td>
<td>Medium, hand-written SQL</td>
<td>Medium</td>
</tr>
</tbody></table>
<p>Encryption deserves more thought than a table cell. A key stored next to the data it protects is not much protection, and where that key lives matters more than which cipher you picked. We cover key storage and threat modeling in <a href="https://stacklynlabs.com/blog/securing-local-first-applications-a-flutter-architecture-study/">securing local-first applications in Flutter</a>.</p>
<h2>A decision tree for 2026</h2>
<p>Work down the list and stop at the first match.</p>
<ol>
<li><strong>Are you on Realm?</strong> Plan a move to drift or ObjectBox now. Deprecation was announced two years ago.</li>
<li><strong>Does your app need to run on the web?</strong> Use drift. Use <code>hive_ce</code> instead if your data really is simple key-value.</li>
<li><strong>Is your data relational?</strong> Orders with line items, invoices with payments, anything you would draw as linked tables: use drift.</li>
<li><strong>Is it settings, caches, a sync queue, or modest per-user records you read by ID?</strong> Use <code>hive_ce</code>.</li>
<li><strong>Do you need indexed object queries on mobile and desktop only?</strong> Use <code>isar_community</code> if you accept a bug-fix-only fork, or ObjectBox if you would rather have a vendor behind it. If neither appeals, drift does the same job with SQL.</li>
<li><strong>Are you on original <code>hive</code> today?</strong> Move to <code>hive_ce</code>. It is the smallest migration on this page.</li>
<li><strong>Are you on original <code>isar</code> today?</strong> Move to <code>isar_community</code> to stay buildable, then decide calmly whether drift is your long-term home.</li>
<li><strong>Are you on <code>sqflite</code> and happy?</strong> Stay. Consider drift when you want type-safe queries and generated migrations.</li>
</ol>
<h2>Migration paths off stalled packages</h2>
<table>
<thead>
<tr>
<th>From</th>
<th>To</th>
<th>Effort</th>
<th>What changes</th>
<th>What usually bites</th>
</tr>
</thead>
<tbody><tr>
<td><code>hive</code></td>
<td><code>hive_ce</code></td>
<td>Low</td>
<td>Package names in <code>pubspec.yaml</code> and imports; <code>hive_generator</code> becomes <code>hive_ce_generator</code>; rerun <code>build_runner</code></td>
<td>Other packages that still depend on <code>hive</code> transitively; stale generated adapters; cached CI builds</td>
</tr>
<tr>
<td><code>isar</code></td>
<td><code>isar_community</code></td>
<td>Low to medium</td>
<td>Swap the runtime and generator packages; same v3 API</td>
<td>Analyzer and <code>source_gen</code> constraint changes in the 3.3.x releases clashing with your other generators</td>
</tr>
<tr>
<td><code>isar</code></td>
<td><code>drift</code></td>
<td>High</td>
<td>Collections become tables, queries become SQL or drift's query builder, plus a one-time data copy on first launch</td>
<td>Watchers and query code rewritten everywhere they are used</td>
</tr>
<tr>
<td><code>realm</code></td>
<td><code>drift</code> or <code>objectbox</code></td>
<td>High</td>
<td>Full rewrite of models and queries; ObjectBox is closer to Realm's object model, drift if you need web or SQL</td>
<td>Sync was already removed, so you need your own sync layer either way</td>
</tr>
<tr>
<td><code>sqflite</code></td>
<td><code>drift</code></td>
<td>Medium</td>
<td>Describe your existing tables in drift and move queries over; the SQLite file format is the same</td>
<td>Matching drift's schema version to the one your users already have on device</td>
</tr>
</tbody></table>
<p>For the two <code>isar</code> rows there is a third route, <code>isar_plus</code>, and a reason not to wait: the original <code>isar</code> 3.1.0+1 Android binaries are not 16 KB aligned. Our <a href="https://stacklynlabs.com/blog/isar-alternatives-flutter/">isar_community vs isar_plus vs drift comparison</a> covers what we measured and what each migration actually involves.</p>
<p>Even the "low" row is not three lines of pubspec. Before you ship a <code>hive</code> to <code>hive_ce</code> swap, run <code>flutter pub deps</code> and look for anything else still pulling in the original package, because two copies of Hive in one app is a confusing failure. Then open a copy of a real production box with the new build and check every record type reads back. The <code>hive_ce</code> package page has no explicit file-compatibility statement, so we tested it ourselves: our <a href="https://stacklynlabs.com/blog/migrate-hive-to-hive-ce/">step-by-step Hive to Hive CE migration guide</a> covers what happened to existing box files, the transitive dependency fix, and the point where rolling back stops working.</p>
<p>The rows marked high are a rewrite of your storage layer, and so is starting from scratch: a schema, adapters or table classes, a backup and restore path, and tests against real data, all before the app does anything a customer would pay for. That is days of work even when it goes well. If you would rather start from a working storage layer, <a href="https://stacklynlabs.com/product/stockpilot/">StockPilot, our offline POS and inventory app</a>, ships with its product catalog, sales and JSON backup and restore already built on Hive (its latest release runs on <code>hive_ce</code>), and <a href="https://stacklynlabs.com/product/vet-vault/">Vet Vault keeps pet medical records, reminders and documents</a> in a local Hive CE store with no server. Its latest release (v1.2.0) already runs on the maintained <code>hive_ce</code> fork, so it is a working example of the first row of the migration table.</p>
<h2>Where to go from here</h2>
<p>If the decision tree pointed you toward a local-first build and you would rather not wire the storage layer yourself, browse <a href="https://stacklynlabs.com/products/?cat=mobile-applications">our offline-first Flutter apps</a>, each one running with no backend. When you are ready to add a server back into the picture, <a href="https://stacklynlabs.com/blog/handling-data-synchronization-and-conflict-resolution-in-offline-apps/">data synchronization and conflict resolution in offline apps</a> covers the part that breaks most often.</p>
<h2>References and further reading</h2>
<ul>
<li><a href="https://docs.flutter.dev/app-architecture/design-patterns/offline-first">Flutter docs: Offline-first support</a>, the official repository-as-source-of-truth pattern</li>
<li><a href="https://pub.dev/packages/hive_ce">hive_ce on pub.dev</a></li>
<li><a href="https://pub.dev/packages/isar_community">isar_community on pub.dev</a></li>
<li><a href="https://pub.dev/packages/drift">drift on pub.dev</a> and <a href="https://drift.simonbinder.eu/platforms/encryption/">drift's encryption guide</a></li>
<li><a href="https://pub.dev/packages/objectbox">objectbox on pub.dev</a></li>
</ul>
<hr />
<p><em>Further reading: <a href="https://stacklynlabs.com/blog/isar-alternatives-flutter/">Isar alternatives for Flutter, tested</a></em></p>
]]></content:encoded></item><item><title><![CDATA[Flutter Bluetooth Thermal Printer Not Printing: Fixes]]></title><description><![CDATA[Paired but silent, ? instead of ₹, a logo cut in half, or nothing on iOS: seven causes of thermal printer failures and the fix for each.]]></description><link>https://stacklynlabs.hashnode.dev/flutter-thermal-printer-troubleshooting</link><guid isPermaLink="true">https://stacklynlabs.hashnode.dev/flutter-thermal-printer-troubleshooting</guid><category><![CDATA[Flutter]]></category><category><![CDATA[Mobile Development]]></category><category><![CDATA[bluetooth]]></category><category><![CDATA[Android]]></category><category><![CDATA[iOS]]></category><dc:creator><![CDATA[Stacklyn Labs]]></dc:creator><pubDate>Mon, 09 Nov 2026 03:19:29 GMT</pubDate><content:encoded><![CDATA[<p><em>Originally published on <a href="https://stacklynlabs.com/blog/flutter-thermal-printer-troubleshooting/">Stacklyn Labs</a>.</em></p>
<p>Your client's shop opens tomorrow. The Flutter app finds the receipt printer, Settings says paired, you tap Print, and nothing happens. Or something does: half a logo, a row of <code>?</code> where the rupee sign should be, every item name wrapped onto two lines. A Flutter Bluetooth thermal printer not printing is rarely one bug. It is usually one of seven, in different layers: the connection, the Bluetooth type, the code page, the document format, the paper width, the image, or a built-in printer that was never Bluetooth.</p>
<p>The pages that rank for this are package READMEs and vendor forum threads. They show how to call a plugin, not why the paper stays blank. This post works backwards from the symptom.</p>
<p>Printing is one part of running a shop with no connection; the rest is in our guide to <a href="https://stacklynlabs.com/guides/offline-first-business-apps/">choosing an offline business app</a>.</p>
<p>On the evidence: we did not bench-test printers for this post. Versions, platform behaviour and printer specs come from pub.dev, Android and Apple developer docs, package source and vendor spec sheets, checked on October 21, 2026. Some of it we learned the hard way: an earlier version of our own POS app had print errors that failed silently and a ₹ sign that never printed.</p>
<h2>Flutter thermal printer not printing: quick diagnosis</h2>
<table>
<thead>
<tr>
<th>Symptom</th>
<th>Likely cause</th>
<th>First fix to try</th>
</tr>
</thead>
<tbody><tr>
<td>Printer listed, connect fails or times out</td>
<td>Paired but not connected, or another phone holds the link</td>
<td>Turn off Bluetooth on nearby phones, power-cycle the printer, reconnect</td>
</tr>
<tr>
<td>Works on Android 11, not on Android 12+</td>
<td>Missing <code>BLUETOOTH_CONNECT</code> / <code>BLUETOOTH_SCAN</code> runtime permission</td>
<td>Declare and request the Android 12 permissions</td>
</tr>
<tr>
<td>Works on Android, never appears on iOS</td>
<td>Bluetooth Classic (SPP) printer</td>
<td>BLE-capable or Wi-Fi printer for iOS</td>
</tr>
<tr>
<td><code>?</code>, wrong letters or an exception on é, €, ₹</td>
<td>Wrong code page, or a character no code page has</td>
<td>Select the right page; print other scripts as an image</td>
</tr>
<tr>
<td>Sent a PDF, nothing printed</td>
<td>ESC/POS printers do not read PDF</td>
<td>Send ESC/POS bytes, or use the system print route</td>
</tr>
<tr>
<td>Lines wrap, columns drift</td>
<td>Layout for 80 mm on a 58 mm printer, or the reverse</td>
<td>Match paper size in the generator and your column widths</td>
</tr>
<tr>
<td>Logo prints as noise, cut off, or stops halfway</td>
<td>Not 1-bit, too wide, or sent faster than the link or printer takes it</td>
<td>Resize, dither, send in strips</td>
</tr>
<tr>
<td>Sunmi-style handheld, no Bluetooth printer found</td>
<td>Built-in printer uses a vendor print service</td>
<td>Use the vendor SDK plugin</td>
</tr>
</tbody></table>
<p>First rule out the boring causes: paper loaded the right way up (thermal paper marks on one side only), cover closed, battery charged. Many printers print a self-test page if you hold the feed button while powering on; the manual will say. If that prints, the hardware is fine and the problem is in your app.</p>
<h2>Paired is not connected</h2>
<p>Android's Bluetooth docs separate the two. Paired means the devices know each other and share a link key. Connected means they currently share an RFCOMM channel and can send data. A printer can sit in Settings as paired for months while nothing in your app is connected to it.</p>
<p><strong>Another device holds the printer.</strong> The Android docs note that RFCOMM allows one connected client per channel at a time. If the owner's personal phone connected yesterday and is still nearby with Bluetooth on, your connect call fails. Android's socket connect gives up after about 12 seconds.</p>
<p><strong>Android 12 permissions.</strong> Apps targeting Android 12 (API 31) or higher need <code>BLUETOOTH_CONNECT</code> to talk to paired devices and <code>BLUETOOTH_SCAN</code> to discover new ones. Both are runtime permissions, granted through the Nearby devices prompt; the manifest alone is not enough. On Android 11 and lower, the legacy <code>BLUETOOTH</code> and <code>BLUETOOTH_ADMIN</code> permissions apply, and scanning also needs <code>ACCESS_FINE_LOCATION</code> at runtime.</p>
<pre><code class="language-xml">&lt;!-- Android 11 and lower --&gt;
&lt;uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" /&gt;
&lt;uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" /&gt;
&lt;uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" /&gt;

&lt;!-- Android 12 and higher --&gt;
&lt;uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /&gt;
&lt;uses-permission android:name="android.permission.BLUETOOTH_SCAN"
    android:usesPermissionFlags="neverForLocation" /&gt;
</code></pre>
<p>Check what your plugin does. <code>print_bluetooth_thermal</code> (1.2.5, published September 28, 2026) has an <code>isPermissionBluetoothGranted</code> getter that checks <code>BLUETOOTH_CONNECT</code>. It only checks, so request the permission yourself first.</p>
<p><strong>Your app ignores the result.</strong> In <code>print_bluetooth_thermal</code>, <code>connect</code> and <code>writeBytes</code> both return <code>Future&lt;bool&gt;</code>. If you never read it, a failed connection looks exactly like a printer that ignored you. Test the link with the smallest payload there is:</p>
<pre><code class="language-dart">final connected =
    await PrintBluetoothThermal.connect(macPrinterAddress: mac);
if (!connected) throw StateError('Printer did not accept the connection');

// ESC @ (initialise), "TEST", three line feeds
final ok = await PrintBluetoothThermal.writeBytes(
    [0x1B, 0x40, 0x54, 0x45, 0x53, 0x54, 0x0A, 0x0A, 0x0A]);
if (!ok) throw StateError('Write failed');
</code></pre>
<p>If <code>TEST</code> prints, the link works, and everything below is about what you send over it.</p>
<h2>Works on Android, invisible on iPhone: Classic vs BLE</h2>
<p>This one costs a client conversation, because code cannot fix it.</p>
<p>Plenty of low-cost receipt printers speak only Bluetooth Classic with the Serial Port Profile (SPP): open an RFCOMM socket, stream bytes. iOS does not offer it to ordinary apps. An Apple DTS engineer put it plainly on Apple's developer forums in November 2024: Core Bluetooth can reach a Classic device only if it supports GATT over Classic, and SPP-style communication needs the MFi Program and the External Accessory framework. Apple's External Accessory docs add that the accessory's manufacturer decides which third-party apps may talk to it. A generic marketplace printer is unlikely to have your app on that list.</p>
<p>So ask the client which printer they own before you write a line. For Android only, a Classic SPP printer works. For iOS too, you need a printer that also speaks BLE, an MFi printer whose vendor approves your app, or a network printer.</p>
<p>Packages split on the same line. <code>blue_thermal_printer</code> (1.2.3, last published July 19, 2022) describes itself as Android only. <code>print_bluetooth_thermal</code> lists paired devices on Android but nearby devices on iOS, and its latest changelog is about Core Bluetooth fixes, so its iOS side is BLE. <code>flutter_blue_plus</code> (2.3.14, published October 3, 2026) states that Bluetooth Classic is not supported on any platform. If a printer shows up on Android and not on iOS, check whether it advertises BLE before debugging anything.</p>
<h2>Garbage characters: ESC/POS code pages and Flutter encoding</h2>
<p>ESC/POS printers do not understand Unicode. They map single bytes to glyphs through a code page selected with <code>ESC t n</code> (bytes <code>1B 74 n</code>). Bytes 0x20 to 0x7F are ASCII on every page, so English prints. The upper half, 0x80 to 0xFF, differs per page, and that is where é, €, ñ and Cyrillic live.</p>
<p>Three things make this harder than it looks:</p>
<ol>
<li><strong>Page numbers are not universal.</strong> Epson's table lists <code>n = 16</code> as WPC1252, 17 as PC866 (Cyrillic) and 19 as PC858 (Latin with €). At least one other vendor's SDK documents 16 as WPC1250, so the same bytes give Central European glyphs on a different printer.</li>
<li><strong>Available pages depend on the model.</strong> Epson's reference says so, and tells you to check each model's own list.</li>
<li><strong>Your Dart library has its own encoder.</strong> <code>esc_pos_utils_plus</code> (2.0.4, published September 1, 2024) has a <code>Generator</code> whose codec defaults to Latin-1, and its source encodes text with Dart's <code>latin1</code> encoder unless you choose Chinese. That encoder throws an <code>ArgumentError</code> on characters outside Latin-1. ₹ (U+20B9) and € (U+20AC) are both outside it, so <code>gen.text('€5')</code> can throw before a byte leaves the phone, even though the printer's CP1252 page has € at 0x80.</li>
</ol>
<p>The library's answer is printer profiles plus code tables:</p>
<pre><code class="language-dart">final profile = await CapabilityProfile.load(); // or load('XP-N160I')
final gen = Generator(PaperSize.mm58, profile);

var bytes = &lt;int&gt;[];
bytes += gen.reset();
bytes += gen.setGlobalCodeTable('CP1252');
bytes += gen.text('Café latte   4.50');
</code></pre>
<p>The profile tells the library which pages your model has. If your printer is not in <code>CapabilityProfile.getAvailableProfiles()</code>, the default profile is a guess. For a character the page has but Latin-1 lacks, encode the bytes yourself and send them with <code>textEncoded</code>.</p>
<h3>When no code page will do</h3>
<p>Sinhala, Tamil, Hindi, Arabic and Thai need shaping: letters change form and join depending on their neighbours, and Arabic also runs right to left. A one-byte-per-glyph code page cannot express that.</p>
<p>The fallback is to stop sending text. Draw the line or the whole receipt in Flutter with a font that has the script, convert it to a 1-bit image, and send raster data. The phone's text engine does the shaping, and you inherit the image and buffer problems covered further down.</p>
<h2>Sent a PDF, printed nothing: the system print route</h2>
<p>A recurring forum report: someone builds a tidy PDF receipt, sends the file's bytes to the printer, and gets a blank roll or a metre of junk. An ESC/POS printer reads incoming bytes as text and commands, and a PDF contains neither in a form it recognises.</p>
<p>The PDF was not the wrong idea, though. The wrong part was where it went. Render the receipt at receipt width with the <code>pdf</code> package (3.13.1, published September 19, 2026), which has <code>roll57</code> and <code>roll80</code> page formats, and pass it to <code>Printing.layoutPdf</code> from <code>printing</code> (5.15.1, same day). That opens the iOS or Android print dialog and the OS handles the printer. Code pages stop being your problem, because the receipt is drawn with real fonts.</p>
<p>The trade-off is which printers appear. On Android, a Bluetooth receipt printer needs a print service app that supports it. On iPhone, Apple's guide says the printer must be on the same Wi-Fi network, and the dialog lists AirPrint printers, so a Bluetooth-only thermal printer will not show up.</p>
<p>Staying on raw ESC/POS for one client means a code page table per printer model, an image fallback for every script that needs shaping, and a test print on every printer the shop might buy next year. <a href="https://stacklynlabs.com/product/stockpilot/">StockPilot, with printing already wired</a> through the system print dialog, takes that route: receipts at 58 mm, 80 mm or A4, a bundled Noto Sans for Latin, Greek, Cyrillic and symbols like ₹, ₦ and ₱, and complex scripts drawn with the device's own fonts. It does not send raw ESC/POS over Bluetooth, so the same trade-off applies: a Bluetooth-only printer on Android needs a print service app, and on iPhone it prints to AirPrint printers.</p>
<h2>58mm vs 80mm receipt: the width maths</h2>
<p>If you stay on ESC/POS, width is the next thing to break. Many low-cost thermal printers run at 203 dpi, 8 dots per millimetre, and the printable width is narrower than the paper. Citizen's CT-S300 spec gives:</p>
<table>
<thead>
<tr>
<th></th>
<th>58 mm paper</th>
<th>80 mm paper</th>
</tr>
</thead>
<tbody><tr>
<td>Printable width</td>
<td>48 mm, 384 dots</td>
<td>72 mm, 576 dots</td>
</tr>
<tr>
<td>Font A (12 × 24 dots)</td>
<td>32 characters</td>
<td>48 characters</td>
</tr>
<tr>
<td>Font B (9 × 17 dots)</td>
<td>42 characters</td>
<td>64 characters</td>
</tr>
</tbody></table>
<p>Characters per line are dots divided by character width: 384 / 12 = 32, 576 / 9 = 64. Not every printer is 203 dpi. Epson's TM-T88VI is 180 dpi and lists 42, 48 or 56 columns on 80 mm paper. Read the spec sheet for the actual model.</p>
<p><code>esc_pos_utils_plus</code> bakes these in: its <code>PaperSize.width</code> getter returns 384 dots for <code>mm58</code>, 512 for <code>mm72</code> and 576 for <code>mm80</code>. Two mistakes follow:</p>
<ul>
<li><strong>Layout built for 80 mm, printed on 58 mm.</strong> A row padded to 48 characters wraps at 32, and the price lands under the item name. Derive column widths from the paper size, not constants.</li>
<li><strong>Generator set to <code>mm80</code> on a 58 mm printer.</strong> Centring and images are calculated for 576 dots on a 384-dot head. What the printer does with the overflow varies by model, and none of it is a usable receipt.</li>
</ul>
<p>Make paper size a setting the shop can change, and keep each sale as data rather than as printed bytes, so a receipt can be regenerated at either width. If you are still choosing where that data lives, our comparison of <a href="https://stacklynlabs.com/blog/building-zero-latency-mobile-apps-hive-vs-isar-vs-sqlite-choosing-a-flutter-local-database-in-2026/">storing sales offline in a Flutter local database</a> covers the options, and our guide to <a href="https://stacklynlabs.com/blog/offline-pos-architecture-flutter/">offline POS architecture in Flutter</a> covers how to model sales, stock and receipt numbers so a receipt can always be rebuilt.</p>
<h2>Logos that print as noise or stop halfway</h2>
<p>A thermal head has two states per dot, so every image has to become 1 bit per dot. A logo with gradients thresholded straight to black and white turns into blobs. Dithering (Floyd-Steinberg or similar) trades grey for a dot pattern. Resize to the final printed size first, then dither.</p>
<p>In raster format each byte carries 8 horizontal dots, and <code>GS v 0</code> takes the width in bytes, so the width is rounded up to a multiple of 8. <code>esc_pos_utils_plus</code> pads rows for you; if you build bytes yourself, pad every row or the image shears diagonally. Keep the width within the printable dots.</p>
<p>There are two image commands. <code>gen.image()</code> uses <code>ESC *</code>, the older column format. <code>gen.imageRaster()</code> uses <code>GS v 0</code>, which Epson marks obsolete in favour of <code>GS ( L</code>. Printers differ in which they handle well, so if one prints noise, try the other before blaming the image.</p>
<h3>Large images over BLE</h3>
<p>A 384-dot logo 200 dots tall is 48 bytes × 200 rows = 9,600 bytes. Over BLE, each write carries at most the negotiated MTU minus 3 bytes, and the MTU starts at 23. <code>flutter_blue_plus</code> requests 512 on Android and notes that iOS negotiates its own, typically 135 to 255. Split writes to that size, or use a package that does.</p>
<p>The printer has a receive buffer too. Epson lists the TM-T88VI's as 45 bytes or 4 KB, selectable; budget printer listings may not state it at all. Send faster than the head prints and the overflow is lost, which looks like a receipt that stops halfway. <code>print_bluetooth_thermal</code> 1.2.5 fixed exactly this on iOS: its changelog says raster images, QR codes and payloads over a few KB were silently dropping packets on iOS 18 and later. If big receipts fail on iPhone, update first.</p>
<p>The defensive pattern is several smaller raster commands, each a horizontal strip of the image, written in order with each write awaited. One printer SDK we read uses 24-row strips for this reason.</p>
<h2>Sunmi printer in Flutter: built-in printers are not Bluetooth</h2>
<p>Android POS handhelds from Sunmi and similar vendors have the printer inside the case. Your app does not pair with it; it binds to the vendor's print service on the device. That is why a Bluetooth scan does not find it.</p>
<p>For Sunmi, <code>sunmi_printer_plus</code> (4.1.1, published September 5, 2025) wraps that service. It is Android only, says it follows Sunmi's official inner printer docs, and exposes calls such as <code>SunmiPrinter.printText(...)</code>, <code>lineWrap</code>, <code>printQRCode</code> and <code>cutPaper</code>. It also has <code>printEscPos()</code> for raw bytes, so an existing <code>esc_pos_utils_plus</code> pipeline can be reused. Several methods, including <code>bindingPrinter()</code>, are marked deprecated, and the last release is over a year old, so check the issue tracker against your device model first.</p>
<p>The width and image rules above still apply, and on budget hardware it pays to cache the logo bitmap rather than decode it on every sale.</p>
<h2>Where to go from here</h2>
<p>If the fix has grown into a full integration across several printer models, <a href="https://stacklynlabs.com/hire-us/?service=mobile_app">we take on custom Flutter printer integration work</a>. And since most of these apps end up on budget POS hardware, read our guide to <a href="https://stacklynlabs.com/blog/optimizing-flutter-app-performance-for-older-mobile-devices/">Flutter performance on older mobile devices</a> before the first rollout.</p>
<h2>References</h2>
<ul>
<li>pub.dev: <a href="https://pub.dev/packages/print_bluetooth_thermal">print_bluetooth_thermal</a> (<a href="https://pub.dev/packages/print_bluetooth_thermal/changelog">changelog</a>), <a href="https://pub.dev/packages/esc_pos_utils_plus">esc_pos_utils_plus</a> (<a href="https://github.com/kechankrisna/esc_pos_utils_plus">source</a>), <a href="https://pub.dev/packages/blue_thermal_printer">blue_thermal_printer</a>, <a href="https://pub.dev/packages/flutter_blue_plus">flutter_blue_plus</a>, <a href="https://pub.dev/packages/sunmi_printer_plus">sunmi_printer_plus</a>, <a href="https://pub.dev/packages/printing">printing</a>, <a href="https://pub.dev/packages/pdf">pdf</a></li>
<li>Android developers: <a href="https://developer.android.com/develop/connectivity/bluetooth/bt-permissions">Bluetooth permissions</a>, <a href="https://developer.android.com/develop/connectivity/bluetooth/find-bluetooth-devices">find Bluetooth devices</a>, <a href="https://developer.android.com/develop/connectivity/bluetooth/connect-bluetooth-devices">connect Bluetooth devices</a></li>
<li>Apple: <a href="https://developer.apple.com/documentation/externalaccessory">External Accessory</a>, <a href="https://developer.apple.com/documentation/corebluetooth">Core Bluetooth</a>, <a href="https://developer.apple.com/forums/thread/769197">DTS answer on Classic Bluetooth from iOS apps</a>, <a href="https://support.apple.com/guide/iphone/iph92628b8f/ios">Print from iPhone</a></li>
<li>Epson: <a href="https://download4.epson.biz/sec_pubs/pos/reference_en/escpos/esc_lt.html">ESC t</a>, <a href="https://download4.epson.biz/sec_pubs/pos/reference_en/escpos/gs_lv_0.html">GS v 0</a>, <a href="https://epson.co.nz/pos/products/Printers/DisplaySpecs.asp?id=tmt88vi">TM-T88VI specifications</a></li>
</ul>
<hr />
<p><em>Further reading: <a href="https://stacklynlabs.com/blog/offline-pos-architecture-flutter/">Offline POS architecture in Flutter</a></em></p>
]]></content:encoded></item><item><title><![CDATA[Isar Alternative for Flutter: Community, Plus or Drift?]]></title><description><![CDATA[We tested isar_community, isar_plus and drift against a real Isar 3 file and checked Android 16 KB alignment.]]></description><link>https://stacklynlabs.hashnode.dev/isar-alternatives-flutter</link><guid isPermaLink="true">https://stacklynlabs.hashnode.dev/isar-alternatives-flutter</guid><category><![CDATA[Flutter]]></category><category><![CDATA[Dart]]></category><category><![CDATA[Databases]]></category><category><![CDATA[Android]]></category><category><![CDATA[Mobile Development]]></category><dc:creator><![CDATA[Stacklyn Labs]]></dc:creator><pubDate>Fri, 06 Nov 2026 02:15:59 GMT</pubDate><content:encoded><![CDATA[<p><em>Originally published on <a href="https://stacklynlabs.com/blog/isar-alternatives-flutter/">Stacklyn Labs</a>.</em></p>
<p>Your Flutter app keeps its data in <code>isar</code> 3.1.0+1. It builds, it ships, and your users' data opens every morning. But the last stable Isar release on pub.dev is from April 25, 2023, the 4.0 line has sat at a dev prerelease since August 2023, and Google Play has set a date after which app updates must support 16 KB memory pages. So you look for an Isar alternative for Flutter and find three names: <code>isar_community</code>, <code>isar_plus</code> and <code>drift</code>.</p>
<p>The pages that rank for this explain how to use Isar or list alternatives in a sentence each. None opens a real Isar 3 file with each successor or checks the Android binaries. We did both. The short version: the original Android libraries are not 16 KB aligned, <code>isar_community</code> is the cheap fix, <code>isar_plus</code> is a different database with a familiar API, and drift means leaving the Isar family on purpose.</p>
<p>If you are picking a database from scratch rather than replacing one, start with <a href="https://stacklynlabs.com/blog/building-zero-latency-mobile-apps-hive-vs-isar-vs-sqlite-choosing-a-flutter-local-database-in-2026/">picking a Flutter local database for an offline-first app</a>. This post is only about getting off original Isar.</p>
<p>A note on the evidence: our tests ran in a scratch pure-Dart project on Dart 3.12.0, on Windows, not in a Flutter app on a device. The data was written by <code>isar</code> 3.1.0+1: two collections, a unique index with <code>replace: true</code>, an <code>@enumerated</code> enum, a <code>DateTime</code>, a <code>double</code>, an embedded list, an <code>IsarLink</code> and a <code>@Backlink</code>. The 16 KB result comes from reading the published Android binaries, not from running on a 16 KB device. Versions are from pub.dev on October 13, 2026. Anything not marked as tested comes from docs and changelogs.</p>
<h2>Which Isar alternative for Flutter fits your project</h2>
<table>
<thead>
<tr>
<th>Where you are</th>
<th>Pick</th>
<th>What it costs you</th>
</tr>
</thead>
<tbody><tr>
<td>Shipped app on <code>isar</code> 3.1.0+1, Android updates must keep shipping</td>
<td><code>isar_community</code> 3.3.2</td>
<td>Package and import swap, a regenerate, and a newer code generator toolchain</td>
</tr>
<tr>
<td>Shipped app, planning a long life</td>
<td><code>isar_community</code> now, <code>drift</code> later</td>
<td>A full data-layer rewrite, on your schedule instead of Google's</td>
</tr>
<tr>
<td>Shipped app that now needs web, encryption or string ids</td>
<td><code>isar_community</code> now, then a copy migration to <code>isar_plus</code></td>
<td>Model changes for the v4 API and a copy step you write and test yourself</td>
</tr>
<tr>
<td>New app, wants Isar's object API, needs web or encryption</td>
<td><code>isar_plus</code> 1.3.9</td>
<td>One maintainer, docs that lag the code, no async APIs or watchers on web</td>
</tr>
<tr>
<td>New app with relational data or a long horizon</td>
<td><code>drift</code> 2.35.2</td>
<td>SQL schema and migrations from day one, no Isar code reused</td>
</tr>
</tbody></table>
<h2>Why staying on isar 3.1.0+1 now has a deadline</h2>
<p>Original Isar has stalled. It is not marked discontinued on pub.dev. The last stable release, 3.1.0+1, came out on April 25, 2023, and the newest prerelease, 4.0.0-dev.14, on August 21, 2023. The last repository commit, on June 14, 2025, added a privacy manifest.</p>
<p>Stalled is not broken. <code>isar</code> 3.1.0+1 declares an SDK constraint below Dart 3.0, yet it still resolves and runs on Dart 3.12 (tested). The cost is your toolchain: <code>isar_generator</code> 3.1.0+1 pinned our project to analyzer 5.13.0, source_gen 1.5.0 and build_runner 2.4.13. Every other generator in the app, such as <code>freezed</code>, <code>json_serializable</code> or <code>riverpod_generator</code>, has to fit under that ceiling.</p>
<p>That was a preference problem until Android's page size change turned it into a deadline. We read the ELF <code>PT_LOAD</code> alignment (<code>p_align</code>) of the published Android libraries:</p>
<table>
<thead>
<tr>
<th>Binary</th>
<th>arm64-v8a</th>
<th>x86_64</th>
</tr>
</thead>
<tbody><tr>
<td><code>isar_flutter_libs</code> 3.1.0+1, <code>libisar.so</code></td>
<td>0x1000 (4 KB), not 16 KB aligned</td>
<td>0x1000, not 16 KB aligned</td>
</tr>
<tr>
<td><code>isar_community_flutter_libs</code> 3.3.2, <code>libisar.so</code></td>
<td>0x4000 (16 KB)</td>
<td>0x4000 (16 KB)</td>
</tr>
<tr>
<td><code>isar_plus</code> 1.3.9 release, <code>libisar_plus_android_arm64.so</code></td>
<td>0x4000 (16 KB)</td>
<td>not checked</td>
</tr>
</tbody></table>
<p>Google's <a href="https://developer.android.com/guide/practices/page-sizes">page size guidance</a> says apps targeting Android 15 (API level 35) and higher must support 16 KB memory pages on 64-bit devices on Google Play. It also says that starting February 1, 2027, app updates that do not support 16 KB pages cannot be released.</p>
<p>If your app targets API 35 and still bundles the original <code>libisar.so</code>, the clock is real, and upstream has not published a new build of that binary since 2023. To check your own build, <code>readelf -l</code> on each <code>.so</code> prints an <code>Align</code> value on every <code>LOAD</code> line. Our check shows how the library is built, not how the app behaves on a 16 KB device, so test on one before release.</p>
<h2>isar_community: the same database, rebuilt for 2026</h2>
<p><code>isar_community</code> is the Isar v3 code under a new name. Its README describes a fork "focusing primarily on bug fixes and small updates for version 3." The changelog since the rename is maintenance: libmdbx 0.13.8, 16 KB page support (from 3.2.0-dev.1), an Android namespace, a Linux GLIBC 2.36 fix, dependency bumps. It runs on Android, iOS, Linux, macOS and Windows, with no web support and no built-in encryption, because v3 never had either.</p>
<h3>The swap</h3>
<pre><code class="language-yaml">dependencies:
  isar_community: ^3.3.2                # was isar
  isar_community_flutter_libs: ^3.3.2   # was isar_flutter_libs

dev_dependencies:
  isar_community_generator: ^3.3.2      # was isar_generator
  build_runner: any                     # resolved 2.15.1 for us
</code></pre>
<p>The package name changes, the library name does not:</p>
<pre><code class="language-dart">// before
import 'package:isar/isar.dart';

// after
import 'package:isar_community/isar.dart';
</code></pre>
<h3>You must regenerate before it compiles (tested)</h3>
<p>We tried the lazy route first: swap the packages, keep the old <code>.g.dart</code> files. They fail to compile with a const assertion on <code>Isar.version</code>:</p>
<pre><code class="language-text">Outdated generated code. Please re-run code generation using the latest generator.
</code></pre>
<p>After <code>dart run build_runner build</code>, the new <code>.g.dart</code> differed from the old one in one place: the embedded version string changed from <code>'3.1.0+1'</code> to <code>'3.3.2'</code>. Every record in our v3 file read back identical, including the link, the backlink count, the embedded list and the enum. New writes worked. No data migration step was needed.</p>
<p>The real change is the toolchain: ours moved to analyzer 10.2.0, source_gen 4.2.4 and build_runner 2.15.1. That lifts the analyzer 5 ceiling off your other generators, and also means they all upgrade at once. The runtime package still says Dart 2.17, but <code>isar_community_generator</code> 3.3.2 needs Dart 3.9, so that is your real floor.</p>
<h3>Rollback worked, once</h3>
<p>We reopened the file that <code>isar_community</code> had written to (four records by then) with the original <code>isar</code> 3.1.0+1. All four came back. That is one test on one schema, not a guarantee, so keep backups of real user files anyway.</p>
<p>We made this same swap in a shipping app. <a href="https://stacklynlabs.com/product/rent-folio/">Rent Folio, our offline landlord app template</a>, was built on <code>isar</code> 3.1.0, with the 4 KB aligned Android binaries from the table above. It now runs on <code>isar_community</code>, using the steps in this section: swap the three packages, change the imports, regenerate the <code>.g.dart</code> files, then check that existing data reads back.</p>
<p>We did not test whether <code>isar_flutter_libs</code> and <code>isar_community_flutter_libs</code> can sit in one Flutter app, which happens if another dependency still pulls in <code>isar</code>. Run <code>flutter pub deps</code> and look for a stray <code>isar</code> before you find out on a device. If the same app keeps settings or a cache in Hive, that store has its own version of this problem, and <a href="https://stacklynlabs.com/blog/migrate-hive-to-hive-ce/">the Hive CE migration path</a> covers what breaks there.</p>
<h2>isar_plus: Isar v4 with one maintainer</h2>
<p><code>isar_plus</code> is not a newer v3. Its 1.0.0 changelog says it is based on the Isar v4 architecture, the line Isar's own README still marks as not ready for production. On top of v4 it adds web support (SQLite compiled to WASM, with an IndexedDB fallback), encryption through SQLCipher (SQLite engine only), string ids, an optional SQLite engine and <code>dynamic</code> or <code>Map</code> properties. The code generator ships inside the package. It needs Dart 3.7, Flutter 3.24 and Android minSdk 23.</p>
<p>The API is different enough that you will touch every data access:</p>
<table>
<thead>
<tr>
<th>Isar v3</th>
<th>isar_plus</th>
</tr>
</thead>
<tbody><tr>
<td><code>writeTxn(...)</code></td>
<td><code>writeAsync(...)</code></td>
</tr>
<tr>
<td><code>writeTxnSync(...)</code></td>
<td><code>write(...)</code> (operations are sync by default)</td>
</tr>
<tr>
<td><code>txn(...)</code></td>
<td><code>readAsync(...)</code></td>
</tr>
<tr>
<td><code>Id? id = Isar.autoIncrement</code></td>
<td>non-nullable <code>int id</code>, set with <code>collection.autoIncrement()</code></td>
</tr>
<tr>
<td><code>@enumerated</code></td>
<td><code>@enumValue</code></td>
</tr>
<tr>
<td><code>IsarLink</code>, <code>IsarLinks</code>, <code>@Backlink</code></td>
<td>removed: use embedded objects or your own id fields</td>
</tr>
<tr>
<td><code>replace: true</code> on unique indexes</td>
<td>removed: the latest write always wins</td>
</tr>
</tbody></table>
<p>On web, its limitations page says async APIs and watchers are not supported, everything runs on the main thread, and most environments fall back to IndexedDB.</p>
<p>The docs already lag the code. The README tells you to call <code>Isar.initializeIsarCore(download: true)</code> in unit tests. That method does not exist in 1.3.9; we had to use <code>Isar.initialize([library])</code>, which does not download anything. The limitations page still mentions lazy-loaded links, which v4 removed.</p>
<h3>It cannot open your v3 file, and the attempt changes it (tested)</h3>
<p>Opening our v3 file with <code>isar_plus</code> 1.3.9 failed with:</p>
<pre><code class="language-text">DatabaseError: IsarError: Schema error: Could not deserialize existing schema.
</code></pre>
<p>The <a href="https://github.com/ahmtydn/isar_plus/blob/main/docs/isar-plus-docs/content/docs/recipes/migrate_from_isar3.mdx">isar_plus migration guide</a> quotes a <code>VersionError</code> instead, so do not search your logs for that one.</p>
<p>The failed open was not harmless. <code>shop.isar</code> grew from 1 MB to 20 MB and its bytes no longer matched the backup. Our data survived: both <code>isar</code> 3.1.0+1 and <code>isar_community</code> 3.3.2 still read all three records. Do not count on that. Back up first, and never point <code>isar_plus</code> at the v3 directory and name.</p>
<h3>The documented side-by-side setup does not resolve (tested)</h3>
<p>The guide's plan is sound: keep the old packages next to <code>isar_plus</code>, copy every record across, delete the old ones. But its pubspec, with <code>isar</code>, <code>isar_flutter_libs</code> and <code>isar_generator</code> 3.1.0+1 beside <code>isar_plus</code>, fails <code>dart pub get</code>. <code>isar_generator</code> wants source_gen <code>^1.2.2</code>, <code>isar_plus</code> wants <code>^4.2.3</code>. Swapping in <code>isar_community_generator</code> 3.3.2 fails too, on analyzer <code>&gt;=8 &lt;11</code> against <code>&gt;=12.1 &lt;14</code>.</p>
<p>The runtimes alone do resolve together. What worked for us:</p>
<ol>
<li>Generate the legacy <code>.g.dart</code> with the old generator first.</li>
<li>Commit it.</li>
<li>Remove the legacy generator, keeping only the legacy runtime.</li>
</ol>
<h3>The guide's build command deletes the file you kept (tested)</h3>
<p>The guide then tells you to run:</p>
<pre><code class="language-bash">dart run build_runner build --delete-conflicting-outputs
</code></pre>
<p>That flag deleted our hand-kept <code>legacy_model.g.dart</code>, and the build failed. Excluding the legacy model in <code>build.yaml</code> fixed it:</p>
<pre><code class="language-yaml">targets:
  $default:
    builders:
      isar_plus:isar_generator:
        generate_for:
          exclude: [lib/legacy_model.dart]
      source_gen:combining_builder:
        generate_for:
          exclude: [lib/legacy_model.dart]
</code></pre>
<h3>The copy itself worked (tested)</h3>
<p>With both packages imported under aliases, the legacy runtime and <code>isar_plus</code> loaded in one Dart process, each with its own native library:</p>
<pre><code class="language-dart">import 'package:isar_community/isar.dart' as legacy;
import 'package:isar_plus/isar_plus.dart' as plus;
</code></pre>
<p>We copied all three records into a new <code>shop_plus</code> instance in the same directory. The <code>IsarLink</code> became an <code>int? categoryId</code> and the enum was mapped by name. Afterwards, <code>collection.autoIncrement()</code> returned 4, so new ids continue past the copied ones. The legacy file was untouched at 1 MB.</p>
<p>So the isar_plus route is a v4 model rewrite, a pubspec the guide gets wrong, a build that deletes your legacy file, and a copy step you must test against real user data. Leaving for drift needs the same copy step plus a rewrite of every query. On an app of any real size, either one is weeks of work before a user sees anything new, and we cannot tell you how many for yours. If what you need is a working offline app rather than a storage project, <a href="https://stacklynlabs.com/products/?cat=mobile-applications">our offline-first Flutter app source code</a> has that layer already built and running without a server.</p>
<h2>drift: leaving the Isar family on purpose</h2>
<p>Drift is a different kind of database. It is a typed layer over SQLite with its own query builder, stream-based watched queries and schema migrations, and it runs on all six Flutter platforms, web included. Nothing from your Isar code carries over: collections become tables, links become foreign keys, watchers become watched queries, and your users' data needs a one-time copy on first launch. We did not test a drift migration, because it is a rewrite by design.</p>
<p>What you get for that is the healthiest maintenance picture of the three. Drift 2.35.2 was published on October 7, 2026, and the repository had commits on October 11. Its lead maintainer has 3,739 commits, and several other people contribute regularly. One thing to know before you start: there is no drift 3.x on pub.dev yet, but the repository already has commits migrating parts of the project to drift3. A major version is in progress, so plan for one more upgrade on drift's side at some point.</p>
<p>Choose drift when you are rewriting anyway or starting fresh. As a way to beat the February 2027 deadline on a shipped app, it is the slowest of the three.</p>
<h2>A fork is a liability you inherit</h2>
<p>Isar itself is the lesson. It was a well-liked database built largely by one author, with 885 commits in the repository and none in its recent history. When those releases stopped, every app built on it inherited the problem. Choosing a fork does not remove that risk. It moves it to someone else, usually one person, and makes you depend on them staying interested.</p>
<p>Look at who is behind each option today:</p>
<table>
<thead>
<tr>
<th></th>
<th>Maintainers</th>
<th>Repository (GitHub, October 13, 2026)</th>
<th>Promise</th>
</tr>
</thead>
<tbody><tr>
<td><code>isar_community</code></td>
<td>One main maintainer doing nearly all recent merges; an outside memory-leak fix landed in July 2026</td>
<td>193 stars, 51 open issues, last commit September 8, 2026</td>
<td>Bug fixes and small updates for v3</td>
</tr>
<tr>
<td><code>isar_plus</code></td>
<td>One person, with no other human contributor in the top list</td>
<td>73 stars, 5 open issues, last commit August 4, 2026</td>
<td>A v4-based engine with web, encryption and an SQLite option</td>
</tr>
<tr>
<td><code>drift</code></td>
<td>Long-running lead maintainer plus regular contributors</td>
<td>3,290 stars, 211 open issues, last commit October 11, 2026</td>
<td>Ongoing, with a major version in progress</td>
</tr>
</tbody></table>
<p>A fourth fork, <code>isar_db</code>, also shows up in search: two releases, the latest 1.0.1+1 from October 2025. We did not test it.</p>
<p>None of this says either fork is bad. <code>isar_community</code> did exactly what it promised and shipped 16 KB binaries the original never got. But when you adopt a fork, plan as if you may one day be its maintainer:</p>
<ul>
<li>Pin exact versions rather than carets, so an upgrade is always a decision.</li>
<li>Keep a tested export of every collection to plain JSON or SQL. If the fork stalls, leaving becomes a data copy instead of an archaeology project.</li>
<li>Watch the repository's commits and issues as well as its pub.dev page.</li>
<li>Write down which native binary ships in your app, and check its alignment again whenever Android's requirements move.</li>
</ul>
<h2>Pre-migration checklist</h2>
<ol>
<li>Copy real <code>.isar</code> files off a test device and keep them out of the app directory.</li>
<li>Check <code>p_align</code> on every <code>.so</code> in your release APK, not only Isar's.</li>
<li>Run <code>flutter pub deps</code> and look for any package that still pulls in <code>isar</code>.</li>
<li>Confirm Dart 3.9 or later for <code>isar_community_generator</code>, or Dart 3.7, Flutter 3.24 and minSdk 23 for <code>isar_plus</code>.</li>
<li>List your other code generators and check they accept the new analyzer range.</li>
<li>Regenerate every <code>.g.dart</code>; never edit the version string by hand.</li>
<li>Open the copied files with the new build and compare every collection.</li>
<li>For <code>isar_plus</code>, give the new database its own name, and exclude legacy models in <code>build.yaml</code> before running <code>build_runner</code>.</li>
<li>Keep one release where you could still roll back before deleting the old data.</li>
</ol>
<h2>Where to go from here</h2>
<p>If you would rather not spend your next sprint on this, <a href="https://stacklynlabs.com/hire-us/?service=mobile_app">we can plan and run your Flutter app's database migration</a> for you. And since neither <code>isar_community</code> nor the original v3 encrypts data at rest, read <a href="https://stacklynlabs.com/blog/securing-local-first-applications-a-flutter-architecture-study/">where to keep encryption keys in a local-first Flutter app</a> before you decide how much protection your stored data needs.</p>
<h2>References</h2>
<ul>
<li><a href="https://pub.dev/packages/isar">isar</a>, <a href="https://pub.dev/packages/isar_community">isar_community</a>, <a href="https://pub.dev/packages/isar_plus">isar_plus</a> and <a href="https://pub.dev/packages/drift">drift</a> on pub.dev</li>
<li><a href="https://github.com/isar-community/isar-community">isar_community repository</a> and its <a href="https://pub.dev/packages/isar_community/changelog">changelog</a></li>
<li><a href="https://github.com/ahmtydn/isar_plus">isar_plus repository</a>, <a href="https://pub.dev/packages/isar_plus/changelog">changelog</a> and <a href="https://github.com/ahmtydn/isar_plus/blob/main/docs/isar-plus-docs/content/docs/recipes/migrate_from_isar3.mdx">migration guide from Isar 3</a></li>
<li><a href="https://github.com/simolus3/drift">drift repository</a></li>
<li><a href="https://github.com/isar/isar">Original Isar repository</a></li>
<li><a href="https://developer.android.com/guide/practices/page-sizes">Android developers: support 16 KB page sizes</a></li>
</ul>
<hr />
<p><em>Further reading: <a href="https://stacklynlabs.com/blog/migrate-hive-to-hive-ce/">Migrate Hive to hive_ce: what breaks after the pubspec swap</a></em></p>
]]></content:encoded></item><item><title><![CDATA[Migrate Hive to hive_ce: What Breaks After the Pubspec Swap]]></title><description><![CDATA[Tested on real Hive 2 box files: typeId 200/201 clashes, transitive hive packages, the one-way typeId door and generator upgrades.]]></description><link>https://stacklynlabs.hashnode.dev/migrate-hive-to-hive-ce</link><guid isPermaLink="true">https://stacklynlabs.hashnode.dev/migrate-hive-to-hive-ce</guid><category><![CDATA[Flutter]]></category><category><![CDATA[Dart]]></category><category><![CDATA[hive]]></category><category><![CDATA[Mobile Development]]></category><category><![CDATA[Databases]]></category><dc:creator><![CDATA[Stacklyn Labs]]></dc:creator><pubDate>Thu, 05 Nov 2026 04:59:17 GMT</pubDate><content:encoded><![CDATA[<p><em>Originally published on <a href="https://stacklynlabs.com/blog/migrate-hive-to-hive-ce/">Stacklyn Labs</a>.</em></p>
<p>Your Flutter app runs on <code>hive</code> 2.2.3. It still opens its boxes and still ships. But <code>flutter pub upgrade</code> keeps stalling on <code>hive_generator</code>, and the last stable <code>hive</code> release on pub.dev is from June 2022. Meanwhile <code>hive_ce</code>, the community continuation of Hive v2, has overtaken the original: 1,317,184 downloads in the last 30 days against 1,131,007 for <code>hive</code> when we checked on October 12, 2026.</p>
<p>So you look up how to migrate Hive to hive_ce. The official page covers swapping the packages and the imports, and calls hive_ce a drop-in replacement for Hive v2. That is true as far as it goes. It does not say whether your users' existing box files still open, what happens when another package in your tree still depends on <code>hive</code>, or that one hive_ce feature removes your ability to roll back.</p>
<p>We ran the migration against real Hive 2 data to find out. This hive_ce migration guide covers the swap in one short section and spends the rest on what the docs leave out. If you are still deciding whether hive_ce is the right home at all, start with <a href="https://stacklynlabs.com/blog/building-zero-latency-mobile-apps-hive-vs-isar-vs-sqlite-choosing-a-flutter-local-database-in-2026/">how hive_ce compares with Isar, drift and SQLite in 2026</a>.</p>
<p>A note on the evidence: our tests ran in a scratch pure-Dart project on Dart 3.12.0, on Windows, not in a Flutter app on a device. Anything below about <code>initFlutter</code> comes from the hive_ce source, changelogs and issue tracker.</p>
<h2>The swap the docs already cover</h2>
<p>Three package names change in <code>pubspec.yaml</code>. These are the current versions on pub.dev as of October 12, 2026:</p>
<pre><code class="language-yaml">dependencies:
  hive_ce: ^2.20.2          # was hive
  hive_ce_flutter: ^2.4.0   # was hive_flutter

dev_dependencies:
  hive_ce_generator: ^1.11.3  # was hive_generator
  # keep your existing build_runner entry
</code></pre>
<p>Then every import changes:</p>
<pre><code class="language-dart">// before
import 'package:hive/hive.dart';
import 'package:hive_flutter/hive_flutter.dart';

// after
import 'package:hive_ce/hive_ce.dart';
import 'package:hive_ce_flutter/hive_ce_flutter.dart';
</code></pre>
<p>The import change is not optional. With <code>hive</code> removed and the old imports left in place, the analyzer stops at <code>uri_does_not_exist</code> on <code>package:hive/hive.dart</code>.</p>
<p>Three small traps sit inside those few lines:</p>
<ul>
<li><strong>The generator is on 1.x, not 2.x.</strong> <a href="https://github.com/IO-Design-Team/hive_ce/issues/62">Issue #62</a> is a user who copied hive_ce's version number into <code>hive_ce_generator: ^2.8.0+3</code> and got a version-solving failure.</li>
<li><strong>The SDK floor is Dart 3.4.</strong> The README's getting-started snippet shows <code>sdk: ^3.0.0</code>, but all three packages declare <code>^3.4.0</code> on pub.dev.</li>
<li><strong>hive_ce_flutter 2.4.0 needs Flutter 3.44.0 or later.</strong> On an older Flutter, <code>^2.4.0</code> will not resolve. Use <code>hive_ce_flutter: ^2.3.4</code> instead: the 2.3.x line needs Flutter 3.27.0 or later, and the same constraint still picks up 2.4.0 once you upgrade Flutter.</li>
</ul>
<h2>Your existing box files open unchanged</h2>
<p>The migration page says Hive v4 data is not compatible. It never says outright that Hive 2 files are.</p>
<p>We tested it. With <code>hive</code> 2.2.3 and <code>hive_generator</code> 2.0.1 we wrote four boxes: a typed box of <code>Product extends HiveObject</code> (with <code>String</code>, <code>double</code>, enum, <code>DateTime</code> and <code>List&lt;String&gt;</code> fields, under both an auto-increment key and a string key), an untyped box holding a mixed map, a <code>LazyBox</code>, and an AES-encrypted box.</p>
<p>We saved what Hive 2 read back as a baseline, then opened the same files under <code>hive_ce</code> 2.20.2 in three states: after only the pubspec and import swap, after regenerating adapters with <code>hive_ce_generator</code>, and after a full move to <code>GenerateAdapters</code>. In all three, every value, every key and every <code>HiveObject.key</code> matched the baseline, including the lazy and encrypted boxes. No data migration step was needed.</p>
<p>The limits: one model, one platform, not your schema on an Android phone. Before you ship, copy a real production box off a test device and open it with the new build.</p>
<h2>Check typeIds 200 and 201 before you upgrade a Flutter app</h2>
<p>This is the biggest gap in the official guide, and it only affects Flutter apps.</p>
<p>Since <code>hive_ce_flutter</code> 2.0.0, a release its changelog marks as breaking, <code>Hive.initFlutter()</code> registers a <code>ColorAdapter</code> at typeId 200 and a <code>TimeOfDayAdapter</code> at typeId 201 for you. If one of your models already uses 200 or 201, your own registration throws <code>There is already a TypeAdapter for typeId 200</code>. That is <a href="https://github.com/IO-Design-Team/hive_ce/issues/105">issue #105</a>, filed by a developer migrating from the original packages. In <a href="https://github.com/IO-Design-Team/hive_ce/issues/291">issue #291</a>, closed February 2026, the complaint was that the reserved IDs were undocumented.</p>
<p>Run this before you touch the pubspec:</p>
<pre><code class="language-bash">grep -rnE "typeId *[:=] *20[01]\b" lib/
</code></pre>
<p>It catches both <code>@HiveType(typeId: 200)</code> annotations and hand-written adapters with <code>final int typeId = 201;</code>.</p>
<p>If you get a hit, do not renumber your model. Changing a typeId orphans every record already stored under it. Move the Flutter adapters instead: since <code>hive_ce_flutter</code> 2.3.0 their IDs are configurable. In the current source, <code>initFlutter</code> takes them as optional positional parameters:</p>
<pre><code class="language-dart">Future&lt;void&gt; initFlutter([
  String? dir,
  HiveStorageBackendPreference backendPreference =
      HiveStorageBackendPreference.native,
  int? colorAdapterTypeId,      // default 200
  int? timeOfDayAdapterTypeId,  // default 201
  bool useMaterialUi = false,
])
</code></pre>
<p>Pick two IDs no model of yours uses. If you stored <code>Color</code> values through the old ecosystem's adapter, read <a href="https://github.com/IO-Design-Team/hive_ce/issues/182">issue #182</a> first: that format is not compatible, and a bug reading legacy colour data was only fixed in <code>hive_ce_flutter</code> 2.3.2.</p>
<h2>Find any package that still pulls in <code>hive</code></h2>
<p>Your pubspec can be clean while your dependency tree is not. Two common sources of the original package:</p>
<ul>
<li><code>hydrated_bloc</code> 9.1.5 and older depend on <code>hive ^2.0.0</code>. It moved to <code>hive_ce</code> in 10.0.0, released January 2025.</li>
<li><code>hive_flutter</code> 1.1.0 depends on <code>hive</code>, so a forgotten <code>hive_flutter</code> line brings it back.</li>
</ul>
<p>Find them with this (use <code>dart pub deps</code> for a pure Dart package):</p>
<pre><code class="language-bash">flutter pub deps | grep -E "\bhive(_flutter|_generator)? [0-9]"
</code></pre>
<p>Anything it prints is the original package, not the CE one.</p>
<h3>What two copies of Hive do</h3>
<p>We reproduced this with both packages installed. They run as two separate engines: <code>identical(ce.Hive, old.Hive)</code> returns <code>false</code>, and each has its own adapter registry and open boxes.</p>
<p>Opening the same box from both failed. On Windows the error was:</p>
<pre><code class="language-text">PathAccessException: lock failed, path = 'data_both\shared.lock'
</code></pre>
<p>That wording is Windows only; other platforms word it differently. Either way it looks like a package that cannot open its box, not like two copies of Hive.</p>
<h3>The override shim</h3>
<p>The best fix is upgrading the offending package. If you cannot, the hive_ce repository ships a stand-in <code>hive</code> package under <code>overrides/hive</code> for exactly this case. This is the <code>dependency_overrides</code> entry from the <a href="https://docs.hive.isar.community/migrations/transitive_hive_dependencies.md">Hive CE docs on transitive Hive dependencies</a>, which we used as is:</p>
<pre><code class="language-yaml">dependency_overrides:
  hive:
    git:
      url: https://github.com/IO-Design-Team/hive_ce
      ref: 18f92b53295e9eb77ebd4830d905a72cd404a126
      path: overrides/hive
</code></pre>
<p>Pub resolved <code>hive 0.0.0 from git ... (overridden)</code>. After that, <code>identical()</code> returned <code>true</code>, and a write through one import was visible through the other: one engine, one box.</p>
<p>The costs: every machine that resolves dependencies, CI included, needs git and access to GitHub. You are pinned to one commit, so check the docs for a newer <code>ref</code> when you upgrade. And you still list <code>hive_ce</code> as a direct dependency. Treat the shim as a bridge until the other package moves.</p>
<h2>The one-way door: typeIds above 223</h2>
<p>Rolling back works up to a point: data <code>hive_ce</code> wrote with the same model and plain types read back correctly in <code>hive</code> 2.2.3.</p>
<p>The point is typeId 224. Original Hive caps custom typeIds at 223, and <code>hive_ce</code> 2.10.0 raised the limit to 65439. Once you register an adapter above 223 and write with it, the original package can no longer read that box. We tested typeId 300 in <code>hive</code> 2.2.3 and got two different failures:</p>
<ul>
<li>registering the adapter: <code>HiveError: TypeId 300 not allowed.</code></li>
<li>opening the box without it: <code>HiveError: Cannot read, unknown typeId: 21. Did you forget to register an adapter?</code></li>
</ul>
<p>The 21 is not your ID. It appears to be the marker hive_ce writes for an extended typeId; that is what we observed, not something the docs state.</p>
<p>So keep a rollback window. Ship the plain migration first, let it run in production for a release or two, and only then allow typeIds above 223.</p>
<h2>What changes in your adapters and toolchain</h2>
<p>Your old generated <code>.g.dart</code> files compile against <code>hive_ce</code> as they are, so regeneration can wait if you want a smaller first diff. When you do run <code>dart run build_runner build</code>, three things change:</p>
<table>
<thead>
<tr>
<th>Old <code>hive_generator</code> output</th>
<th><code>hive_ce_generator</code> output</th>
<th>Effect</th>
</tr>
</thead>
<tbody><tr>
<td><code>final int typeId = 0;</code></td>
<td><code>final typeId = 0;</code></td>
<td>None</td>
</tr>
<tr>
<td><code>break;</code> in enum adapter cases</td>
<td>removed</td>
<td>None</td>
</tr>
<tr>
<td><code>fields[1] as double</code></td>
<td><code>(fields[1] as num).toDouble()</code></td>
<td>A stored int no longer crashes a double field</td>
</tr>
</tbody></table>
<p>The bigger change is what the old generator was holding back. In a fresh Dart 3.12 project, adding <code>hive_generator</code> 2.0.1 resolved <code>analyzer</code> 6.4.1, <code>source_gen</code> 1.5.0 and <code>build_runner</code> 2.4.13, and downgraded <code>test</code> and other packages. After switching to <code>hive_ce_generator</code>, the same project resolved <code>analyzer</code> 14.5.0, <code>source_gen</code> 4.3.0 and <code>build_runner</code> 2.16.2. If your app also uses <code>freezed</code>, <code>json_serializable</code> or any other generator, <code>hive_generator</code> was probably the anchor keeping them all old. We infer that from the version constraints; we have not seen an issue that states it. It is still the best reason to migrate that is not about maintenance.</p>
<p>If you're on Isar instead, the original <code>isar_generator</code> holds your toolchain back in the same way, and its Android binaries add a deadline of their own. We tested <a href="https://stacklynlabs.com/blog/isar-alternatives-flutter/">the Isar alternatives for Flutter against a real Isar 3 file</a>.</p>
<p>Add it up and the three-line migration is really a typeId audit, a dependency tree review, a decision about a git override, a regeneration, and a read-back test against real user data. On an app you wrote yourself, plan for a careful day. On a codebase you inherited, budget longer, because first you have to learn where every box is opened. If what you need is a working offline app rather than a storage migration project, <a href="https://stacklynlabs.com/product/stockpilot/">StockPilot, an offline Flutter POS whose data lives in local Hive boxes</a>, is the kind of codebase this guide was written for. Its latest release made this move: StockPilot now runs on <code>hive_ce</code>, with the same data format as before.</p>
<h2>Moving to GenerateAdapters (optional)</h2>
<p><code>hive_ce</code> would rather you stop annotating models with <code>@HiveType</code> and <code>@HiveField</code> and list them in one <code>@GenerateAdapters</code> annotation. You do not need this to migrate. If you do it, the <a href="https://docs.hive.isar.community/migrations/hive_types_to_generate_adapters.md">documented route</a> worked for us:</p>
<ol>
<li>Move any <code>@HiveField</code> default values into constructor parameter defaults. Our test model had none, so we did not exercise this step.</li>
<li>Enable the migrator builder in <code>build.yaml</code> and run <code>build_runner</code>:</li>
</ol>
<pre><code class="language-yaml">targets:
  $default:
    builders:
      hive_ce_generator|hive_schema_migrator:
        enabled: true
</code></pre>
<ol start="3">
<li>It writes <code>lib/hive/hive_adapters.dart</code> containing <code>@GenerateAdapters([AdapterSpec&lt;Product&gt;(), AdapterSpec&lt;Category&gt;()])</code>, a <code>lib/hive/hive_adapters.g.yaml</code> with your existing typeIds and field indexes preserved, and a registrar.</li>
<li>Revert <code>build.yaml</code>, remove the annotations and <code>part</code> directives from your models, and build again.</li>
</ol>
<p>Our Hive 2 data still read back identically. Two things caught us that the docs do not mention.</p>
<p><strong>The registrar file moves.</strong> During the migrator run it is written to <code>lib/hive_registrar.g.dart</code>. After the final build it lives at <code>lib/hive/hive_registrar.g.dart</code>, so the old import breaks with <code>Error when reading 'lib/hive_registrar.g.dart'</code>. Update the import in <code>main.dart</code>.</p>
<p><strong>The <code>.g.yaml</code> becomes the source of truth for field indexes.</strong> Its header says to check it into version control. Do that. Renaming a field now means editing the yaml by hand, as the docs say. We did not test losing the file, but regenerating without it risks reassigned indexes, which is the kind of mistake that corrupts reads quietly.</p>
<h2>Deprecations the analyzer will not flag</h2>
<p>hive_ce's <a href="https://docs.hive.isar.community/deprecated/deprecation_policy.md">deprecation policy</a> is that APIs are never marked deprecated in code, because the project aims never to introduce breaking changes. So your build stays quiet while the docs list these as replaced:</p>
<ul>
<li><code>@HiveType</code> and <code>@HiveField</code>, in favour of <code>GenerateAdapters</code></li>
<li><code>HiveObject</code></li>
<li><code>HiveList</code></li>
<li><code>ValueListenable</code> and <code>box.listenable()</code>, in favour of <code>box.watch()</code></li>
</ul>
<p>None of this has to change during the migration. It matters later, because <code>HiveObject</code> and <code>HiveList</code> are what block <code>IsolatedHive</code>, the multi-isolate API added in 2.11.0. Do not adopt it in the migration branch. The <a href="https://docs.hive.isar.community/advanced/isolates.md">isolates docs</a> say that if you use it, you must use it everywhere in place of <code>Hive</code>; it does not support <code>HiveObject</code> or <code>HiveList</code>, and most calls become async. That is a refactor of every data access in the app.</p>
<p>The same 2.11.0 release tightened some type rules: boxes of type <code>Map</code> must be <code>Map&lt;dynamic, dynamic&gt;</code>, boxes of type <code>Iterable</code> must be <code>Iterable&lt;dynamic&gt;</code>, and custom objects in a <code>BoxCollection</code> must be JSON-serializable. If you open something like <code>Box&lt;Map&lt;String, dynamic&gt;&gt;</code> today, find it before you upgrade.</p>
<h2>Pre-migration checklist</h2>
<ol>
<li>Copy real box files off a test device or staging install.</li>
<li>In a Flutter app, grep for typeId 200 and 201.</li>
<li>Run <code>flutter pub deps</code> and look for <code>hive</code>, <code>hive_flutter</code> or <code>hive_generator</code>.</li>
<li>Upgrade or override any package still on <code>hive</code>, starting with <code>hydrated_bloc</code> 9.x.</li>
<li>Search for boxes typed as a <code>Map</code> or <code>Iterable</code> with non-dynamic type arguments.</li>
<li>Confirm Dart 3.4 or later and, for <code>hive_ce_flutter</code> 2.4.0, Flutter 3.44.0 or later.</li>
<li>Swap the three packages and every import.</li>
<li>Open the copied boxes with the new build and compare every record type.</li>
<li>Clear CI caches so no stale <code>.g.dart</code> or resolved <code>hive</code> survives.</li>
</ol>
<h2>What not to do</h2>
<ul>
<li><strong>Do not renumber a model's typeId</strong> to dodge the 200/201 collision. Move the Flutter adapters instead.</li>
<li><strong>Do not use a typeId above 223</strong> until the migrated release has proven itself. It ends your rollback option.</li>
<li><strong>Do not set <code>hive_ce_generator: ^2.x</code>.</strong> The generator is on 1.x.</li>
<li><strong>Do not adopt <code>IsolatedHive</code> in the migration branch.</strong></li>
<li><strong>Do not leave the <code>.g.yaml</code> out of git</strong> if you move to <code>GenerateAdapters</code>.</li>
</ul>
<h2>Where to go from here</h2>
<p>If you would rather start from apps whose local storage layer is already built and running without a server, browse <a href="https://stacklynlabs.com/products/?cat=mobile-applications">our offline-first Flutter app templates</a>. And since an encrypted box is only as safe as the place you keep its key, <a href="https://stacklynlabs.com/blog/securing-local-first-applications-a-flutter-architecture-study/">securing local-first applications in Flutter</a> covers where that key should live.</p>
<h2>References</h2>
<ul>
<li><a href="https://pub.dev/packages/hive_ce">hive_ce on pub.dev</a>, <a href="https://pub.dev/packages/hive_ce_flutter">hive_ce_flutter</a> and <a href="https://pub.dev/packages/hive_ce_generator">hive_ce_generator</a></li>
<li><a href="https://docs.hive.isar.community/migrations/hive_to_hive_ce.md">Hive CE docs: migrating from Hive v2</a></li>
<li><a href="https://github.com/IO-Design-Team/hive_ce/blob/main/hive_flutter/CHANGELOG.md">hive_ce_flutter changelog</a>, for the 200/201 registration (2.0.0) and configurable IDs (2.3.0)</li>
<li><a href="https://github.com/IO-Design-Team/hive_ce/blob/main/hive/CHANGELOG.md">hive_ce changelog</a>, for the 65439 typeId limit (2.10.0) and the 2.11.0 type rules</li>
<li>GitHub issues <a href="https://github.com/IO-Design-Team/hive_ce/issues/62">#62</a>, <a href="https://github.com/IO-Design-Team/hive_ce/issues/105">#105</a>, <a href="https://github.com/IO-Design-Team/hive_ce/issues/182">#182</a> and <a href="https://github.com/IO-Design-Team/hive_ce/issues/291">#291</a></li>
<li><a href="https://docs.hive.isar.community/migrations/transitive_hive_dependencies.md">Hive CE docs: transitive Hive dependencies</a> and <a href="https://github.com/IO-Design-Team/hive_ce/tree/main/overrides/hive">the override package in the hive_ce repository</a></li>
<li><a href="https://docs.hive.isar.community/migrations/hive_types_to_generate_adapters.md">Hive CE docs: HiveTypes to GenerateAdapters</a></li>
</ul>
<hr />
<p><em>Further reading: <a href="https://stacklynlabs.com/blog/building-zero-latency-mobile-apps-hive-vs-isar-vs-sqlite-choosing-a-flutter-local-database-in-2026/">Choosing a Flutter local database in 2026</a></em></p>
]]></content:encoded></item></channel></rss>