TYPO3 Site Handling: Architecture Notes for Multi-Site Deployments

The problem and what to decide first

TYPO3 version 9 and later resolves the current site from the request hostname and path using YAML files under config/sites//config.yaml. This replaces older TypoScript-based domain detection. A common mistake during upgrades or multi-domain rollouts is to keep TypoScript conditions for domain routing while adding site configuration, or to assume one site entry can serve several unrelated domains. The result is usually a frontend No site found exception, wrong asset URLs, or redirect loops.

Takeaway: treat site handling as trusted administrative infrastructure. Use one site configuration per domain or language tree, declare an explicit base URL and default language, validate in the TYPO3 backend, and clear caches after every change.

Requirements

• TYPO3 v9 or later with Site Handling enabled.
• File system access to config/sites/ or backend access to the Site Management module.
• DNS or host entries that resolve each domain to the TYPO3 installation.
• A page tree with language root pages if you serve multiple languages.

Terms: a site identifier is the directory name under config/sites/ and is referenced in links and backend references. A base URL is the public address TYPO3 uses to generate absolute links. A language fallback tells TYPO3 which language to render when a page has no translation.

Smallest suitable design

Start with one site per domain. If a domain serves multiple languages, configure those languages inside that site’s config.yaml rather than creating a separate site for each language unless the domains differ.

Example site configuration

Run file edits on the application server where TYPO3 is installed. The example below defines two sites. Replace example.com, example.de, and page IDs with your own values.

# config/sites/example_com/config.yaml
base: 'https://www.example.com/'
languages:
  -
    title: English
    languageId: '0'
    base: /
    locale: en_US.UTF-8
    iso-639-1: en
    hreflang: en
    direction: ltr
    flag: gb
    errorPageTitle: ''
    navigationTitle: ''
    websiteTitle: ''
    fallbackType: strict
    fallback: []

# config/sites/example_de/config.yaml
base: 'https://www.example.de/'
languages:
  -
    title: German
    languageId: '0'
    base: /
    locale: de_DE.UTF-8
    iso-639-1: de
    hreflang: de
    direction: ltr
    flag: de
    errorPageTitle: ''
    navigationTitle: ''
    websiteTitle: ''
    fallbackType: strict
    fallback: []

Avoid wildcard hostnames such as *.example.com unless a specific routing requirement justifies them. Wildcards make it harder to audit which site handles a request and can mask missing configuration for new subdomains.

Trust and data boundaries

Site configuration is trusted administrative data. It is edited by administrators in the backend or directly in files, and it is not intended for public output. Do not give frontend or untrusted backend users write access to config/sites/. Do not store database credentials, API keys, or encryption secrets in config.yaml; it is configuration, not a credential store.

The data boundary is the HTTP request. TYPO3 matches the incoming hostname and path against site configurations. If an attacker controls a hostname that resolves to your server, they cannot alter config.yaml, but they can trigger a mismatch that produces a No site found exception. That exception is an availability issue, not a data leak, provided error pages do not expose internal paths.

Operational checks

1. Open the TYPO3 backend and go to Site Management > Sites. Confirm each site appears with the expected base URL and languages.
2. Request each configured domain in a browser or with curl. Verify the correct language root page loads and no No site found exception appears.
3. After editing any config.yaml, clear system caches. Run this on the application server with write access to var/ and typo3temp/:

bin/typo3 cache:flush

Expected check: the command completes without permission errors, and subsequent frontend requests reflect the new configuration. Risk: cache flushing temporarily increases database load and slows page delivery until caches are rebuilt.

Monitor backend logs after deployment for site resolution warnings. A spike in No site found entries usually means a domain is missing from site configuration or DNS points to the wrong server.

Failure modes

Symptom	Likely cause	Check
Frontend shows "No site found"	Hostname does not match any site base URL	Compare request host against base in all config/sites/*/config.yaml
Asset URLs use wrong domain	Incorrect base URL or missing scheme	Inspect generated page source and confirm base includes https://
Redirect loop between languages	Conflicting language fallback or TypoScript redirect rules	Disable custom TypoScript domain conditions temporarily and retest
Untranslated content or 404 after language switch	Missing fallback language or unpublished translation	Verify language configuration and page translation status in the backend

Conditions that change the design

• Headless TYPO3 used as an API backend: site handling still resolves the site, but you may need custom middleware to map API hostnames to sites.
• Multiple domains sharing one content root: use separate site configurations pointing to the same page tree root, with distinct base URLs and language settings.
• Static page caching proxy in front of TYPO3: base URL changes require cache invalidation in the proxy, not only in TYPO3.
• Moving site configuration from files to database: backend references and page links tied to site identifiers can break if identifiers change.

Rollback

Editing config.yaml and flushing caches changes system state. To roll back, restore the previous config.yaml from backup and run bin/typo3 cache:flush again. Verify the site list in Site Management > Sites after restoration.

Practical verification

Change one language fallback in config.yaml, clear caches, request a page without a translation in the default language, and confirm the fallback language renders instead of a 404. If it does not, review the fallback chain and clear caches again.

Limitations

Site handling resolves the site and language, but it does not render translations. TypoScript, Fluid templates, and page language configuration still control whether content is translated. This note covers TYPO3 v9 and later; behavior in earlier versions differs because they rely on TypoScript domain records.