The tank looked fine. The fish were not fighting. There was no visible aggression, no torn fins, no chasing. Then one of the tetras stopped coming out at feeding time. A week later it was dead. Another followed. Then a third. Nobody could explain what happened — the water tested fine, the fish looked healthy, and there was no disease. The problem was not the water or the disease. The problem was that the tetras were living with a cichlid that did not attack them, it just made them too stressed to eat.
The short version
Compatibility is four things: water parameters overlapping, adult size, temperament, and territory. Parameters must overlap meaningfully — temperature, pH and hardness all need a shared range. Adult size determines whether one fish becomes food for another. Temperament must be compatible across peaceful, semi-aggressive or aggressive categories. Territory and space must be sufficient for every species' needs. Get all four or the tank does not work. A failure on any axis is a compatibility failure.
The four axes of compatibility
Compatibility is not a single yes-or-no question. It is the intersection of four independent requirements, and a pairing that passes three and fails one still fails. You cannot compensate for a parameter mismatch with extra space, and you cannot compensate for temperament incompatibility with perfect water. Here are the four things that have to align.
Water parameters must overlap
Every species has a preferred range for temperature, pH, hardness and salinity. Compatibility means the ranges overlap enough that both fish are inside their tolerance, not that one is comfortable and the other is surviving. A fish that tolerates pH 6.0 to 7.5 and a fish that needs 7.5 to 8.5 can technically both survive at 7.5, but one is at the edge of its range and the other is at the opposite edge. That is not an overlap, it is a compromise, and compromises produce chronic stress.
Temperature is the easiest to check and the hardest to fudge. Goldfish need 18 to 22 degrees Celsius. Most tropical species need 24 to 28. There is no overlap. Keeping goldfish warm shortens their lifespan. Keeping tropicals cold suppresses their immune system. The pairing does not work, and no amount of filtration or space changes that.
Hardness is the parameter people forget. African rift lake cichlids need hard alkaline water with a pH above 7.8 and substantial mineral content. Amazonian tetras need soft acidic water with a pH below 7.0 and negligible hardness. You can force both into neutral water, and both will live, but neither will thrive, breed or show full coloration. Use your tap water's natural chemistry as the baseline and stock species that suit it rather than fighting it.
Adult size and the predation rule
If it fits in the mouth, it is food. This is not aggression, it is opportunism, and peaceful species do it as readily as predatory ones. A full-grown angelfish is peaceful by cichlid standards, but it will eat neon tetras because neon tetras fit in its mouth. The angelfish is not misbehaving. You stocked prey with a predator.
Judge compatibility by adult size, not the size in the shop. Oscars are sold at 5 centimeters and reach 30. Common plecos are sold at 8 centimeters and reach 45. Bala sharks are sold as community fish and grow large enough to eat everything else in the tank. Ask what the adult size is, verify it independently, and stock for that size rather than the juvenile you are bringing home.
The rule works in reverse, too. Small peaceful fish can nip the fins of large slow-moving species, not out of aggression but because the fins look like food. Serpae tetras and tiger barbs are notorious for shredding the fins of angelfish, bettas and guppies despite being smaller and nominally less aggressive.
Temperament
Temperament is the general behaviour of the species: peaceful, semi-aggressive, or aggressive. Peaceful species ignore each other except during breeding. Semi-aggressive species establish territory or hierarchy but do not usually kill unless crowded. Aggressive species fight conspecifics, other species, or anything that moves.
Peaceful with peaceful works. Semi-aggressive with semi-aggressive works if there is enough space. Aggressive with aggressive works in species tanks with careful planning. Peaceful with aggressive does not work. The peaceful fish spend every moment hiding, stop eating, and die of stress even if they are never physically attacked.
Temperament varies with sex, maturity, breeding status and individual personality. A species described as peaceful can produce an aggressive individual, and a species described as semi-aggressive can include individuals that are outright predatory. This is why a compatibility chart is a starting point, not a guarantee.
Space and territory
Territory is not the same as tank size. A 200-litre tank is not enough for two male bettas because bettas are territorial and will fight regardless of space. A 200-litre tank may be enough for a group of semi-aggressive cichlids if it is structured with enough sight barriers that each fish can claim a discrete area and defend it without constant contact with rivals.
Territorial species need a defendable space. That usually means a cave, a plant cluster, a rock pile or a corner with broken sightlines. If there are three territorial fish and two caves, the third fish is harassed constantly. If there are three territorial fish and six caves, the aggression drops because everyone has space and alternatives.
Swimming level matters, too. Species that occupy the same water column layer compete even if they are otherwise compatible. A tank full of surface dwellers will fight for position. A tank with surface, mid-water and bottom dwellers distributes the bioload and the competition across three layers. Stock across levels, not just within one.
The problems that only show up later
Some compatibility failures are obvious in the first week. Others take a month or more to show up, by which time you have already decided the tank is fine and stopped monitoring. Here are the ones that appear slowly.
Fin nippers in small groups
Species like tiger barbs and serpae tetras are listed as semi-aggressive, which undersells the problem. In small groups they nip constantly. In groups of ten or more the aggression is distributed within the school and other species are mostly ignored. Keeping three tiger barbs in a community tank turns them into a harassment squad. Keeping twelve turns them into a school.
Schooling fish kept in threes
Schooling fish are social obligates. A school of three is not a school, it is three stressed individuals. Most schooling species need at least six to feel secure, and many need ten or more to display natural behaviour. Underschooled fish hide, refuse to eat in the open, and become targets for aggression because they look weak.
Sex ratios
Two male bettas will kill each other. Two male gouramis will fight until one is too injured to recover. Many cichlids need to be kept one male to multiple females, or in groups large enough that aggression diffuses. Livebearers like guppies and mollies need at least two females per male or the females are harassed to exhaustion. Ask about sex ratios before you stock, not after the tank has turned into a battlefield.
Fish sold at 3 centimeters that reach 30
The common pleco, the bala shark, the Chinese algae eater, the tinfoil barb, the iridescent shark — all sold as small peaceful community fish, all reaching sizes that make them unsuitable for anything smaller than a 600-litre tank. Shops stock what sells, and juveniles sell. Verify the adult size before you buy, and if the answer is vague, assume the fish grows large.
Nocturnal versus diurnal conflicts
Nocturnal species like many catfish and loaches are active when the lights go off. Diurnal species are asleep. If your peaceful daytime community includes a large nocturnal predator, you may find fish missing in the morning with no sign of aggression during the day. The aggression happened at night, when you were not watching.
Competition for the same cave
Two territorial bottom dwellers will fight over the best cave even if there are other caves available. The best cave is usually the one with the most cover, the best flow, or the most defensible entrance. Add more hiding spots than you think you need, and add variety so different fish prefer different spots.
Classic freshwater mismatches
Some pairings fail so reliably that they deserve their own warning. Here are the combinations that appear in beginner tanks constantly and fail for predictable reasons.
| Pairing | Why it fails | What to do instead |
|---|---|---|
| Bettas with fin nippers | Tiger barbs, serpae tetras and similar species shred the betta's fins. The betta cannot escape and becomes chronically stressed. | Pair bettas with small peaceful species like ember tetras, corydoras or snails. Avoid anything remotely nippy. |
| Small tetras with large cichlids | Neon tetras fit in the mouth of an adult angelfish or severum. Peaceful cichlids are still predators to anything bite-sized. | Stock tetras with fish that cannot eat them, or stock cichlids with fish too large to be prey. |
| Goldfish with tropicals | Temperature ranges do not overlap. Goldfish need cold water, tropicals need warm water. One is always stressed. | Stock goldfish with other coldwater species, or stock a separate tropical tank. |
| Shrimp with most cichlids | Shrimp are live food. Even peaceful cichlids hunt them. Dwarf shrimp in a cichlid tank last hours. | Keep shrimp in a species tank or with small peaceful fish that do not predate inverts. |
| Plecos in small tanks | Common plecos reach 45 centimeters. They are sold at 8. A 100-litre tank is not large enough for an adult, and they produce exceptional waste. | Stock bristlenose plecos or other dwarf species that stay under 15 centimeters. |
| Gouramis with each other | Males are territorial and will fight. Mixing species or keeping multiple males usually ends with one dead and the others stressed. | Keep one male gourami per tank, or keep a species group with heavy planting and broken sightlines. |
Saltwater compatibility is a different problem
Saltwater compatibility follows the same four axes, but the emphasis shifts. Temperature and salinity ranges are narrower, so parameter mismatches are less common. Territory and aggression are more pronounced, so stocking order, tank structure and conspecific aggression dominate the conversation.
Conspecific aggression
Many marine species tolerate other species but attack their own. Dottybacks, hawkfish, and many tangs will kill a second individual of the same species in anything smaller than a very large reef. This is why you see single specimens of most saltwater fish rather than groups.
Order of introduction
Adding the most aggressive fish last is even more important in saltwater than freshwater. A clownfish added to an empty tank will claim the entire space. A clownfish added to an established reef with existing fish treats the new territory as already occupied and integrates more peacefully. Tangs, triggerfish and dottybacks should always go in last.
Reef-safe versus not
Reef-safe means the fish will not eat corals, anemones or ornamental inverts. Not reef-safe means it will. Butterflyfishes, many angelfish, pufferfish and triggerfish are coral predators. Keeping them in a reef tank means choosing which you value more, the fish or the coral.
Invert and coral compatibility
Some inverts prey on corals. Some corals sting fish. Some anemones eat fish that wander into their tentacles at night. Check compatibility between every organism in the tank, not just the fish. A coral-safe fish and a fish-eating anemone still creates a compatibility failure.
Tangs and territory
Tangs need swimming room and established algae to graze. Adding multiple tangs to a small reef creates constant fighting. One tang per tank is the safe recommendation unless the tank is large enough and structured well enough to support discrete territories. The "tang police" warnings you see online are mostly correct.
Temperament tiers
Understanding where a species sits on the temperament spectrum tells you what it can be housed with. Here is how the tiers break down in practice.
| Tier | Typical behaviour | What they can be housed with | Common examples |
|---|---|---|---|
| Peaceful | Ignore other species entirely except during active breeding. No territory, no aggression, no hierarchy beyond mild schooling behaviour. | Other peaceful species of similar size. Some can coexist with semi-aggressive species if the tank is large and well-structured. | Neon tetras, corydoras, otocinclus, cherry shrimp, most rasboras, hatchetfish, kuhli loaches. |
| Semi-aggressive | Establish territory or hierarchy. May chase rivals but rarely kill unless breeding, overcrowded, or underfed. Behaviour escalates in small tanks. | Other semi-aggressive species of similar size and temperament, or larger peaceful species that will not be bullied. | Dwarf cichlids, most gouramis, many barbs, rainbowfish, some larger tetras, some angelfish. |
| Aggressive | Constant territory defense, hierarchy enforcement, or conspecific fighting. Will injure or kill rivals, incompatible species, or anything that intrudes. | Species tanks, or very large tanks with other aggressive species of similar size. Avoid mixing with peaceful fish entirely. | Oscars, Jack Dempseys, many larger cichlids, red-tailed sharks, Chinese algae eaters, some triggerfish. |
| Predatory | Hunt and consume live prey. Anything small enough to eat will be eaten. Not aggressive in the territorial sense, just opportunistic. | Species tanks, or with fish too large to be prey. Avoid mixing with anything bite-sized. | Arowanas, larger pufferfish, lionfish, groupers, peacock bass, wolf fish. |
Order of introduction and how to add fish
The order in which fish enter the tank changes the outcome. Territorial species added to an empty tank claim the whole space. The same species added to an established community integrates into an existing hierarchy and claims less.
Least aggressive first
Start with peaceful schooling fish. They establish no territory and create a calming baseline. Add semi-aggressive fish next, once the tank has an existing population and some structure to the social environment. Add the most aggressive or territorial species last, when the tank is already occupied and the newcomer has to negotiate rather than dominate.
Rearrange decor when adding to an established territory
If you are adding a territorial fish to a tank that already has territorial residents, rearrange the rocks, driftwood and plants before introduction. This disrupts the existing territories and forces everyone to re-establish at the same time, which distributes the aggression and gives the newcomer a chance to claim space rather than being treated as an intruder into an established domain.
Quarantine
Every new fish should spend two to four weeks in a quarantine tank before joining the display. This is not just disease prevention, it is behaviour observation. A fish that looks peaceful in the shop may turn aggressive once acclimated. Quarantine gives you time to observe real behaviour before the fish is in contact with your established stock.
Adding in groups
Schooling species should be added as a complete group, not one or two at a time. Adding six tetras at once establishes a school. Adding two tetras, waiting two weeks, then adding two more creates two stressed pairs rather than a cohesive group. The social structure forms in the first few days, and late arrivals are often excluded.
Reading a compatibility check properly
A compatibility check is a data-driven starting point, not a final answer. It compares species databases and flags conflicts, but it cannot account for your specific tank size, your decor, your water parameters, or the individual temperaments of the fish you own.
A warning is not a prohibition
A compatibility warning means the pairing has known failure modes under common conditions. It does not mean the pairing is impossible. Angelfish and neon tetras are flagged incompatible because adult angelfish eat neons, but if the angelfish were raised with a large school of adult neons from juvenile size, predation is less likely. The warning is correct, but context matters.
A green result is not a guarantee
Two species marked compatible can still fail if the tank is too small, the parameters are at the edge of both ranges, or one fish is an outlier. Compatibility assumes good conditions: appropriate tank size, proper parameters, adequate hiding spots, and typical individual temperament. Remove any of those and the green result becomes unreliable.
Tank size, decor and individual temperament all move the answer
A pairing that fails in a 100-litre tank may succeed in a 400-litre tank with heavy planting and broken sightlines. A species described as semi-aggressive can produce peaceful individuals and aggressive individuals in the same spawn. Use the compatibility check to rule out pairings that will not work under any conditions, then adjust for your specific setup and monitor behaviour after introduction.
How TankSync fits
Compatibility is a database problem as much as it is a behaviour problem. You need to know the parameter range, adult size, temperament and territory needs for every species, and then compare all of them against each other. TankSync automates that comparison with an 857-species database and real-time conflict detection.
The 857-species database with per-species parameter ranges and temperament
TankSync tracks 173 freshwater fish, 179 saltwater fish, 61 freshwater inverts, 126 saltwater inverts, 82 corals and 40 plants. Each entry includes the temperature range, pH range, hardness preference, salinity, adult size, temperament tier, diet, swimming level, and territory needs. When you run a compatibility check, those ranges are compared across every species in your tank and every species you are considering.
Running a compatibility check before you buy
Add the species you are considering to your tank list as a draft. Run a compatibility check. The app compares it against every existing species and flags conflicts: parameter mismatch, size incompatibility, temperament clash, territory conflict. Fix the conflicts or choose a different species before you leave the shop.
The compatibility score with conflicts listed by severity
The tank health score includes a 25 percent weighting for stocking compatibility. Each conflict is categorized as minor, moderate or severe, and the score reflects the cumulative risk. A minor conflict might be a borderline parameter overlap. A severe conflict is a predator housed with prey-sized fish. The score gives you a single number that summarizes compatibility risk across the whole tank.
AI compatibility analysis on Pro
The Pro tier includes AI-powered compatibility analysis that goes beyond the database. Describe your tank setup, your planned stocking, and your concerns. The AI evaluates compatibility in context: your tank size, your decor, your water source, and your experience level. It suggests stocking adjustments, territory improvements, and parameter targets specific to your planned community.
Checking compatibility in TankSync
Before you add a species, verify it works with what you already have:
- Open your aquarium and tap the species list.
- Tap "Add species" and search for the fish, invert or coral you are considering.
- View the species profile to see parameter ranges, adult size, temperament and territory needs.
- Run the compatibility check to see conflicts with your existing stock.
- Review the conflicts by severity. Severe conflicts mean the pairing does not work. Minor conflicts may be acceptable depending on your tank.
- For detailed advice, use the AI compatibility analysis on Pro to evaluate your specific setup.
General guidance, not a prescription
Compatibility data reflects typical behaviour under typical conditions. Individual temperament varies, and a species described as peaceful can produce aggressive individuals. Tank size, decor, parameter stability, sex ratios, and order of introduction all affect outcomes. A compatibility check is a starting point, not a guarantee.
TankSync's species database, compatibility engine and AI features are informational and are not veterinary advice. Verify compatibility against your own observations and, where animals are unwell or behaviour is concerning, consult an aquatic veterinarian.
Frequently asked questions
How do I know if two fish are compatible?
Check four things: water parameters must overlap meaningfully, which means temperature, pH and hardness all fall inside a shared range. Adult size must be considered, not juvenile size, because anything that fits in the mouth becomes food. Temperament must be compatible across peaceful, semi-aggressive or aggressive categories. Territory and swimming level must not create a conflict, which means giving territorial species enough space and not overstocking a single water column layer. A green light on one axis and a red light on another means the pairing does not work.
Can I keep a betta in a community tank?
A single male betta can work in a community tank if you avoid fin nippers, other labyrinth fish, and anything that looks remotely like another betta. Species with long flowing fins, bright colours, or aggressive tendencies will either nip the betta or be attacked by it. Small peaceful schooling fish like ember tetras, corydoras and snails usually work. Female bettas in groups are unpredictable and often establish brutal hierarchies. Two males will fight to the death. The tank needs heavy planting, moderate flow, and no angelfish, barbs, gouramis or other bettas.
Why do my fish keep hiding?
Hiding is usually stress, and the stress usually has a source. The fish may be housed with an aggressive or incompatible tank mate, underschooled so they feel exposed, or placed in water parameters outside their tolerance. Newly added fish hide for a few days while they acclimate, which is normal. Fish that hide for weeks and come out only to feed are frightened, and frightened fish eventually stop eating. Check the compatibility of every species in the tank, verify the school sizes, and test pH, temperature and hardness against each species' preferred range.
Can goldfish live with tropical fish?
No. Goldfish are coldwater fish with an ideal range between 18 and 22 degrees Celsius, while most tropical species need 24 to 28 degrees. That is not an overlap, it is a conflict. Goldfish also grow enormous, produce exceptional waste, and are slow enough that faster tropicals will outcompete them for food. Keeping goldfish at tropical temperatures shortens their lifespan and stresses their metabolism. Keeping tropicals at coldwater temperatures slows their immune function and makes them lethargic. The parameters do not overlap, which means the pairing does not work regardless of temperament.
What order should I add fish to a new tank?
Add the least aggressive species first and the most aggressive last. Peaceful schooling fish establish no territory and create a calming presence. Semi-aggressive fish added to an empty tank will claim the entire space, and every fish added afterwards becomes an intruder. Adding semi-aggressive fish to a tank that already has a peaceful community means they move into an established social structure, which reduces aggression. Rearrange the hardscape when adding a territorial species to an established tank so existing territories are disrupted and everyone resets at once. Quarantine every new arrival for two to four weeks before introduction.
Are compatibility charts reliable?
They are a starting point, not a guarantee. A chart tells you whether two species are generally compatible under good conditions, which means adequate tank size, proper parameters, appropriate decor and no individual outliers. Individual temperament varies, and a species rated peaceful can produce an aggressive individual. Tank size changes the answer: a pairing marked incompatible in a small tank may work in a large one with broken sightlines and multiple territories. Compatibility also depends on sex ratios, school size, and order of introduction. Use a chart to rule out obvious mismatches, then verify against your specific setup.