Multi Tenancy Pitfalls

Multi-tenancy: pitfalls & gotchas

Part of the Multi-tenancy section. Planned / in design.

Multi-tenancy is powerful, but a few traps are worth knowing about. Most are handled by design — this page explains how.

Replying in the wrong company's context

The single most dangerous mistake for staff: you're working "as" Acme, but you meant to reply to a Globex ticket. The defence is in the UI — the active company is shown loudly at all times, and cross-company search results are badged with their client. Always glance at the current-company indicator before replying.

Mapping a free-email domain to a company

Never map gmail.com, outlook.com, yahoo.com, etc. to a company. Two different clients will both have users on those domains, so mapping one would wrongly pull everyone on Gmail into a single client. Free-email senders go to triage and are assigned by hand.

Forgetting to set a client's domain up

If a client emails in before you've registered their domain, their message doesn't error or vanish — it lands in the triage queue, ready to be assigned (and the domain remembered for next time). See Email Routing.

"Are settings shared or separate?" confusion

Some settings are global (mailbox connections, AI keys, the company list, staff), some are per-company (domains, SLAs, categories, branding). For config that could go either way — categories, SLAs, workflows — FreeITSM uses global defaults with per-company overrides, so you never have to flip a risky "global or per-company?" switch. See Settings.

Expecting separate databases per client

FreeITSM keeps all companies in one database, separated by a company tag on every record — logical isolation, not physical. This is deliberate and keeps the system lightweight. If a client contractually requires their data in a physically separate database, their own encryption keys, or a specific data-residency region, FreeITSM is honestly not the right tool — see Scope.

The same email address in two companies

Because a requester is a single global person (keyed by verified email), the same address is never split into two conflicting accounts — one person has one login, and their tickets are filed per company. See Users & self-service.

For self-hosters: why the rollout is gradual

Multi-tenancy touches every module, and the biggest engineering risk is a single overlooked query leaking one client's data into another's view. That's why it's built one module at a time, behind the scenes, with every step kept backward-compatible and invisible until it's proven. You will never be asked to pull a half-finished state onto your live system — main stays stable throughout. See the roadmap issue (#24).