What the checker actually checks
Six constraints, evaluated in severity order:
- Parameter compatibility.Temperature, pH, and GH ranges from FishBase + manufacturer care sheets. Species whose ranges don't overlap can't both be at their target at once — surfaces as a hard Won't work.
- Predator-prey lookup. Documented cases like angelfish + neon tetras: angels eat neons consistently. The engine flags these as hard incompatibilities.
- Per-species tank-size minimum.Each species has a real footprint requirement (a school of 6 corydoras needs a 20-gallon long, not a 10-gallon tall). Surfaces when the species doesn't fit even before bioload math.
- Schooling minimums. Solo or paired schoolers (neon tetras under 6, corydoras under 6, kuhli loaches under 5) display severe stress and lose color. The checker flags below-minimum counts as cautions.
- Adjusted bioload. Inches-per-gallon math weighted by body type — corydoras at 0.8 (slim), angelfish at 1.5 (tall), mystery snails at 0.3 (invertebrate). Working ratio under 0.7 is comfortable; 0.7-1.0 is workable but tight; over 1.0 is overstocked.
- Aggression conflicts.Two male bettas, two male dwarf gourami, betta + guppy long fins — the social dynamics that don't show up in pure parameter or bioload math but reliably kill fish in real tanks.
Why this is structurally different from incumbents
The reigning compatibility checker (AqAdvisor) returns a flat probability score from a hand-tuned database. It's slow, dated, mobile-broken, and asks you to trust the percentage on faith. This checker exposes every constraint individually with the message that drove it, the suggested fix per constraint, and three additional species that fit. The point is to show WHY a combo fails, not just grade it. Once you can see that “the angelfish eats the neons, but everything else is fine,” you can decide what to drop — which is the actual stocking question.
What this calculator does NOT model
- KH (carbonate hardness) — relevant for pH stability in soft-water and Rift Lake setups.
- Flow preference — riverine species (white cloud minnows, hillstream loaches) want strong current; blackwater species want still.
- Substrate preference — kuhli loaches need sand, not gravel; common plecos need driftwood.
- Breeding-context dynamics — many species have different group- structure needs when actively breeding.
- Sex-ratio harassment — livebearers (guppies, mollies) need 1 male per 2-3 females or females get harassed; the checker doesn't enforce this yet.
FAQ
How is this different from the stocking density calculator?
The stocking-density calculator answers "is this stocking safe for the tank?" — it checks bioload, schooling minimums, and tank-size requirements for a single proposed setup. The compatibility checker is broader: it adds parameter overlap (temperature / pH / GH), aggression-conflict detection, predator-prey lookup, and auto-suggests three additional species that would also fit your selection. Use the stocking calculator for "how many of one species fit" questions, the compat checker for "do these species work together" questions.
What does "Cautions apply" actually mean?
Cautions apply means the combination CAN work in a stable tank, but you're at the edge of one or more constraints. Common causes: parameter ranges overlap by only a few degrees of temperature or 0.2 of pH (workable in a stable tank, fragile in one with parameter swings); the bioload ratio is between 0.7 and 1.0 in/gal (workable for experienced keepers with strong filtration, tight for beginners); a species count is at the schooling minimum rather than comfortably above it. Treat cautions as "check this assumption before committing."
Why isn't my favorite species in the dropdown?
The compat checker uses the FishTankMath species database — currently 14 commonly-kept freshwater species (8 with deep-content care guides, 6 thin placeholders shipped 2026-04-29). Coverage will expand as new species pages ship. If you want a specific species added, the dataset is intentionally conservative — better to omit a species than guess at parameters and produce wrong verdicts.
What is the "Upsize nudge"?
When the only blocking constraint is tank size — your species combo is fine but the tank is too small for either bioload or footprint reasons — the checker computes the next standard tank size that would clear the constraint. Common case: 6 corydoras + 6 neon tetras in a 10-gallon hits the bioload ceiling, but the same combo in a 20-gallon long is comfortable. The nudge tells you exactly which tank size unlocks the combo.
Are the suggestions optimal or just compatible?
Compatible, not optimal. The suggester picks species that share your selection's parameter window, fit the remaining bioload headroom, and don't introduce new aggression or predator-prey conflicts. It doesn't optimize for visual variety, color contrast, or ranking by rarity — those are aesthetic decisions outside the math. Treat suggestions as starting points, not prescriptions.
What about parameter ranges I never asked about (KH, hardness, flow)?
Currently the engine checks temperature, pH, and GH (general hardness) — the three parameters that drive most beginner stocking failures. KH (carbonate hardness, drives pH stability) and water-flow preference are not yet modeled. For most beginner community-tank decisions, the temp / pH / GH triad surfaces 80%+ of real conflicts. Specialist tanks (discus, hard-water cichlids, blackwater setups) need more nuance than this calculator provides.
Related
- Stocking density calculator →
- Aquarium volume calculator →
- Schooling minimum group size →
- All species deep guides →
Engine logic in lib/aquarium/compatibility.ts and lib/aquarium/stocking.ts. Species data sourced from FishBase (Tier 1 per FTM editorial policy) for parameter ranges + adult sizes; behavior + schooling minimums from established hobby practice. Where sources diverged, this checker takes the conservative beginner-safe position. Not veterinary advice — for sick fish or tank emergencies, consult an aquatic veterinarian or a qualified local aquarium professional.