| name | typo3-solr |
| description | Expert guidance on Apache Solr search integration for TYPO3: installation, Index Queue, faceting, suggest, PSR-14 events, custom indexers, LLM/vector search (Solr native), DDEV/Docker/production setup, deep debugging & troubleshooting, and file indexing via solrfal. Use when working with solr, search, indexing, facets, suggest, autocomplete, vector search, solrfal, tika. |
| compatibility | TYPO3 13.4 - 14.x |
| metadata | {"version":"1.0.0","related_skills":["typo3-content-blocks","typo3-datahandler","typo3-seo","ai-search-optimization"]} |
Apache Solr for TYPO3
Compatibility: TYPO3 v13.4 LTS (current) and v14.x (when EXT:solr 14.0 releases).
EXT:solr 13.1 targets TYPO3 13.4. A task/14LTS_compatibility dev branch is actively being developed.
All custom PHP code in this skill uses TYPO3 v14 conventions (PHP 8.2+, #[AsEventListener], constructor promotion).
TYPO3 API First: Always use TYPO3's built-in APIs and EXT:solr's TypoScript/PSR-14 events before creating custom implementations. Do not reinvent what EXT:solr already provides.
Sources
This skill is based on the following authoritative sources:
- EXT:solr Documentation
- EXT:tika Documentation
- Version Matrix
- GitHub: TYPO3-Solr/ext-solr
- GitHub: v14 dev branch
- Apache Solr Reference Guide
- Solr Dense Vector Search
- Solr Text to Vector (LLM)
- typo3-solr.com
- hosted-solr.com
- ddev-typo3-solr
- Mittwald Solr Docs
- helhum/dotenv-connector
1. Architecture Overview
EXT:solr connects TYPO3 CMS to an Apache Solr search server, providing full-text search, faceted navigation, autocomplete, and (since Solr 9.8) vector/semantic search.
graph LR
subgraph typo3 [TYPO3 CMS]
Editor[Editor creates/edits content]
Monitor[Monitoring detects changes]
Queue[Index Queue]
Scheduler[Scheduler Worker]
Plugin[Search Plugin]
end
subgraph solr [Apache Solr Server]
Core[Solr Core]
Schema[Schema / Configset]
end
Editor --> Monitor
Monitor --> Queue
Queue --> Scheduler
Scheduler -->|HTTP POST documents| Core
Plugin -->|HTTP GET query| Core
Core --> Plugin
Document Lifecycle
sequenceDiagram
participant E as Editor
participant T as TYPO3
participant M as Monitor
participant Q as Index Queue
participant S as Scheduler
participant Solr as Solr Server
E->>T: Create/edit record
T->>M: DataHandler triggers PSR-14 event
M->>Q: Add/update queue item
Note over Q: tx_solr_indexqueue_item
S->>Q: Poll for pending items
Q->>S: Return items to index
S->>Solr: POST document (JSON)
Solr-->>S: 200 OK
S->>Q: Mark item as indexed
Component Overview
| Component | Package | Purpose | Required? |
|---|
| EXT:solr | apache-solr-for-typo3/solr | Core search integration | Yes |
| EXT:tika | apache-solr-for-typo3/tika | Text/metadata extraction from files | Only for file indexing |
| EXT:solrfal | Funding extension | FAL file indexing into Solr | Only for file indexing |
| EXT:solrconsole | Funding extension | Backend management console | Optional |
| EXT:solrdebugtools | Funding extension | Query debugging, score analysis | Optional (recommended for dev) |
2. Version Compatibility Matrix
| EXT:solr | TYPO3 | Apache Solr | Configset | PHP | EXT:tika | EXT:solrfal |
|---|
| 13.1 | 13.4 | 9.10.1 | ext_solr_13_1_0 | 8.2 - 8.4 | 13.1 | 13.0 |
| 12.1 | 12.4 | 9.10.1 | ext_solr_12_1_0 | 8.1 - 8.3 | 12.1 | 12.0 |
TYPO3 v14 Readiness
EXT:solr does not yet have a stable v14 release. Active development happens on the task/14LTS_compatibility branch (last updated Feb 17, 2026).
Key v14 changes in the dev branch:
- Fluid v5 ViewHelper compatibility
- TSFE removal:
FrontendEnvironment/Tsfe refactored to FrontendSimulation/FrontendAwareEnvironment
ext_emconf.php removed (Composer-only)- TCA
searchFields deprecation handled
- FlexForm registration via
registerPlugin() instead of addPiFlexFormValue()
- New configset:
ext_solr_14_0_0
Testing with the dev branch:
composer require apache-solr-for-typo3/solr:dev-task/14LTS_compatibility
Warning: This branch is WIP. Do not use in production.
CVE-2025-24814 Migration
Apache Solr 9.8.0+ disables loading jar files via lib directive in configsets. The solr-typo3-plugin must be moved from /configsets/ext_solr_*/typo3lib/ to /typo3lib/ at the Solr server root. Docker users: pull image v13.0.1+ -- the migration runs automatically.
3. Installation & Setup
Composer
composer require apache-solr-for-typo3/solr
DDEV Setup
The recommended local development setup uses the ddev-typo3-solr addon:
ddev add-on get ddev/ddev-typo3-solr
ddev restart
Configure .ddev/typo3-solr/config.yaml:
config: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/solr.xml'
typo3lib: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/typo3lib'
configsets:
- name: 'ext_solr_13_1_0'
path: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/configsets/ext_solr_13_1_0'
cores:
- name: 'core_en'
schema: 'english/schema.xml'
- name: 'core_de'
schema: 'german/schema.xml'
Auto-initialize cores on boot in .ddev/config.yaml:
hooks:
post-start:
- exec-host: ddev solrctl apply
Useful DDEV commands:
| Command | Description |
|---|
ddev solrctl apply | Create cores from config |
ddev solrctl wipe | Delete all cores |
ddev solr version | Check Solr version |
ddev launch :8984 | Open Solr Admin UI |
ddev logs -s typo3-solr | View Solr logs |
Docker (Production)
services:
solr:
image: typo3solr/ext-solr:13.1
ports:
- "8983:8983"
volumes:
- solr-data:/var/solr
restart: unless-stopped
volumes:
solr-data:
driver: local
The image ships default cores for all languages. Persistent data is stored at /var/solr (owned by UID 8983).
Standalone Solr
Deploy the configset from EXT:solr into your Solr installation:
cp -r vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/* $SOLR_INSTALL_DIR/server/solr/
Create cores via core.properties files or REST API:
curl -X POST http://localhost:8983/api/cores -H 'Content-Type: application/json' -d '{
"create": {
"name": "core_en",
"configSet": "ext_solr_13_1_0",
"schema": "english/schema.xml",
"instanceDir": "cores/core_en",
"dataDir": "/var/solr/data/core_en"
}
}'
Managed Hosting: Mittwald
Mittwald provides a managed Solr service via their container platform. Use the Terraform module:
module "solr" {
source = "mittwald/solr/mittwald"
solr_version = "9"
solr_core_name = "typo3"
solr_heap = "2g"
}
Access Solr at http://solr:8983 inside the container. For local debugging:
mw container port-forward --port 8983
Managed Hosting: hosted-solr.com
hosted-solr.com by dkd provides pre-configured Solr cores optimized for EXT:solr. Plans start at EUR 10/month (2 indexes, 4000 documents). After creating a core, configure it in your TYPO3 site config using the provided host, port, and path.
TYPO3 Site Configuration
In config/sites/<identifier>/config.yaml:
solr_enabled_read: true
solr_host_read: solr
solr_port_read: '8983'
solr_scheme_read: http
solr_path_read: /
solr_core_read: core_en
For DDEV, use the DDEV hostname and HTTPS port:
solr_host_read: <project>.ddev.site
solr_port_read: '8984'
solr_scheme_read: https
Environment Configuration (helhum/dotenv-connector)
Never hardcode Solr connection details. Use helhum/dotenv-connector for per-environment configuration:
composer require helhum/dotenv-connector
.env (gitignored):
SOLR_HOST=solr
SOLR_PORT=8983
SOLR_SCHEME=http
SOLR_PATH=/
SOLR_CORE_EN=core_en
SOLR_CORE_DE=core_de
.env.example (committed to VCS):
SOLR_HOST=solr
SOLR_PORT=8983
SOLR_SCHEME=http
SOLR_PATH=/
SOLR_CORE_EN=core_en
SOLR_CORE_DE=core_de
In config/system/additional.php, override site config values programmatically or use a post-processing approach. For simple setups, keep .env values and reference them in deployment scripts that generate site config YAML per environment.
4. EXT:tika -- When You Need It (and When Not)
EXT:tika integrates Apache Tika for metadata extraction, language detection, and text extraction from ~1200 file formats.
graph TD
Question{"Do you index files?<br/>(PDF, DOCX, XLSX)"}
Question -->|Yes| NeedTika[Install EXT:tika + EXT:solrfal]
Question -->|No| SkipTika[Skip -- EXT:solr handles<br/>pages and records natively]
NeedTika --> TikaServer["Run Tika Server 3.2.2+<br/>(Docker recommended)"]
Three backends (choose one):
| Backend | Recommended? | Setup |
|---|
| Tika Server | Yes | Standalone Docker container, newest Tika version |
| Solr Cell | Acceptable | Uses Tika built into Solr, no extra service needed |
| Tika App | Deprecated | Requires Java on webserver, do not use |
When you NEED EXT:tika:
- File indexing via EXT:solrfal (search inside PDFs, Word documents, etc.)
- Automatic FAL metadata enrichment (EXIF, XMP, document properties)
- Language detection on uploaded files
When you DON'T need it:
- Only indexing pages and structured records (news, events, products) via Index Queue
- EXT:solr handles page content and record fields natively without Tika
Version: EXT:tika 13.1. Requires Tika Server 3.2.2+ (CVE-2025-54988 fix).
See SKILL-SOLRFAL.md for complete file indexing setup.
5. Configset & Schema
The configset defines how Solr processes and indexes text. EXT:solr ships configsets at Resources/Private/Solr/configsets/ext_solr_13_1_0/.
Structure
ext_solr_13_1_0/
├── conf/
│ ├── solrconfig.xml
│ ├── english/
│ │ └── schema.xml
│ ├── german/
│ │ └── schema.xml
│ └── ... (other languages)
└── typo3lib/ # moved to server root since Solr 9.8
Each language has its own schema.xml with language-specific analyzers (stemmer, stop words).
Dynamic Field Types
Use dynamic field suffixes to add custom fields without modifying the schema:
| Suffix | Type | Multi | Example |
|---|
_stringS | string (not analyzed) | No | category_stringS |
_stringM | string (not analyzed) | Yes | tags_stringM |
_textS | text (analyzed) | No | description_textS |
_textM | text (analyzed) | Yes | keywords_textM |
_intS | integer | No | year_intS |
_floatS | float | No | price_floatS |
_dateS | date | No | published_dateS |
_boolS | boolean | No | active_boolS |
Full reference: Dynamic Fields Appendix
Site Hash Strategy
Since EXT:solr 13.0, the default site hash strategy changed from domain-based (deprecated) to site-identifier-based. Configure in Extension Settings:
siteHashStrategy = 1 (site-identifier, default and recommended)siteHashStrategy = 0 (domain, deprecated, removed in 13.1.x+)
If upgrading from 12.x, you must re-index after switching strategies.
6. Index Queue Configuration
The Index Queue is the central mechanism for getting TYPO3 records into Solr.
graph LR
subgraph monitoring [Record Monitoring]
Edit[Record created/edited]
Event[PSR-14 DataUpdate Event]
end
subgraph queue [Index Queue]
Item["tx_solr_indexqueue_item"]
end
subgraph processing [Processing]
Worker[Scheduler: Index Queue Worker]
Solr[Solr Server]
end
Edit --> Event
Event --> Item
Worker -->|polls| Item
Worker -->|POST document| Solr
Pages
Pages are indexed out of the box. No additional configuration needed. The page indexer sends the rendered page content to Solr.
Custom Records
Index any TYPO3 record table via TypoScript. Full example for EXT:news:
plugin.tx_solr.index.queue {
news = 1
news {
type = tx_news_domain_model_news
fields {
abstract = teaser
author = author
authorEmail_stringS = author_email
title = title
content = SOLR_CONTENT
content {
cObject = COA
cObject {
10 = TEXT
10 {
field = bodytext
noTrimWrap = || |
}
}
}
category_stringM = SOLR_RELATION
category_stringM {
localField = categories
multiValue = 1
}
keywords = SOLR_MULTIVALUE
keywords {
field = keywords
}
tags_stringM = SOLR_RELATION
tags_stringM {
localField = tags
multiValue = 1
}
url = TEXT
url {
typolink.parameter = {$plugin.tx_news.settings.detailPid}
typolink.additionalParams = &tx_news_pi1[controller]=News&tx_news_pi1[action]=detail&tx_news_pi1[news]={field:uid}
typolink.additionalParams.insertData = 1
typolink.returnLast = url
}
}
attachments {
fields = related_files
}
}
}
Content Objects
| Object | Purpose |
|---|
SOLR_CONTENT | Strips HTML/RTE from field content |
SOLR_RELATION | Resolves relations (categories, tags, etc.), supports multiValue = 1 |
SOLR_MULTIVALUE | Splits a comma-separated field into multiple values |
Records Outside Siteroot
To index records stored in sysfolders outside the site tree:
plugin.tx_solr.index.queue.news {
additionalPageIds = 45,48
}
Enable monitoring in Extension Settings: "Enable tracking of records outside siteroot".
Monitoring
EXT:solr detects record changes via PSR-14 events. Two modes:
- Immediate (default): changes are processed directly during the DataHandler operation
- Delayed: changes are queued in
tx_solr_eventqueue_item and processed by a scheduler task ("Event Queue Worker")
Configure via Extension Settings: monitoringType.
7. Search Configuration
Essential Settings
plugin.tx_solr {
enabled = 1
search {
targetPage = 42
initializeWithEmptyQuery = 1
showResultsOfInitialEmptyQuery = 0
trustedFields = url
keepExistingParametersForNewSearches = 1
}
}
Faceting
plugin.tx_solr.search {
faceting = 1
faceting {
facets {
contentType {
label = Content Type
field = type
}
category {
label = Category
field = category_stringM
}
year {
label = Year
field = year_intS
type = queryGroup
queryGroup {
2026 {
query = [2026-01-01T00:00:00Z TO 2026-12-31T23:59:59Z]
}
2025 {
query = [2025-01-01T00:00:00Z TO 2025-12-31T23:59:59Z]
}
2024 {
query = [2024-01-01T00:00:00Z TO 2024-12-31T23:59:59Z]
}
}
}
}
}
}
Facet types: options (default), queryGroup, hierarchy, dateRange, numericRange.
Suggest / Autocomplete
plugin.tx_solr {
suggest = 1
suggest {
numberOfSuggestions = 10
suggestField = spell
showTopResults = 1
numberOfTopResults = 5
additionalTopResultsFields = url,type
}
}
The built-in suggest uses the devbridge/jQuery-Autocomplete library. For a jQuery-free approach, see SKILL-FRONTEND.md.
Sorting, Highlighting, Spellcheck
plugin.tx_solr.search {
sorting = 1
sorting {
defaultOrder = asc
options {
relevance {
field = relevance
label = Relevance
}
title {
field = sortTitle
label = Title
}
created {
field = created
label = Date
}
}
}
results {
resultsHighlighting = 1
resultsHighlighting {
fragmentSize = 200
wrap = <mark>|</mark>
}
}
spellchecking = 1
}
Route Enhancers
SEO-friendly search URLs:
routeEnhancers:
SolrSearch:
type: SolrFacetMaskAndCombineEnhancer
extensionKey: solr
solr:
type: Extbase
extension: Solr
plugin: pi_results
routes:
- routePath: '/search/{q}'
_controller: 'Search::results'
_arguments:
q: q
8. Fluid Templates & Frontend
Template Paths
plugin.tx_solr {
view {
templateRootPaths.10 = EXT:my_ext/Resources/Private/Templates/Solr/
partialRootPaths.10 = EXT:my_ext/Resources/Private/Partials/Solr/
layoutRootPaths.10 = EXT:my_ext/Resources/Private/Layouts/Solr/
}
}
Key Templates
| Template | Purpose |
|---|
Templates/Search/Results.html | Main search results page |
Templates/Search/Form.html | Search form |
Partials/Result/Document.html | Single result item |
Partials/Facets/OptionsFacet.html | Options facet rendering |
Partials/Facets/QueryGroupFacet.html | Query group facet |
Copy default templates from EXT:solr to your extension path and modify them.
9. PSR-14 Events Reference
Monitoring Events
| Event | Fired when |
|---|
VersionSwappedEvent | A version is swapped (workspace publish) |
RecordMovedEvent | A record is moved |
RecordGarbageCheckEvent | A garbage check is triggered |
RecordDeletedEvent | A record is deleted |
PageMovedEvent | A page is moved |
ContentElementDeletedEvent | A content element is deleted |
Data Update Processing Events
| Event | Fired when |
|---|
ProcessingFinishedEvent | Data update processing is complete |
DelayedProcessingQueuingFinishedEvent | Update queued in event queue (delayed mode) |
DelayedProcessingFinishedEvent | Delayed processing complete (scheduler) |
Indexing Events
| Event | Fired when |
|---|
BeforePageDocumentIsProcessedForIndexingEvent | Before page document is processed (add extra documents) |
AfterPageDocumentIsCreatedForIndexingEvent | After page document created (replace/substitute) |
BeforeDocumentIsProcessedForIndexingEvent | Before non-page record document is processed |
BeforeDocumentsAreIndexedEvent | Before documents are sent to Solr (add custom fields) |
Other Events
| Event | Fired when |
|---|
AfterFacetIsParsedEvent | Facet component modification |
AfterUriIsProcessedEvent | URI building in search context |
AfterSiteHashHasBeenDeterminedForSiteEvent | Override calculated site hash |
Example: Add Custom Fields to Documents (v14 Style)
<?php
declare(strict_types=1);
namespace MyVendor\MyExt\EventListener;
use ApacheSolrForTypo3\Solr\Event\Indexing\BeforeDocumentsAreIndexedEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;
#[AsEventListener(identifier: 'my-ext/enrich-solr-documents')]
final class EnrichSolrDocuments
{
public function __invoke(BeforeDocumentsAreIndexedEvent $event): void
{
foreach ($event->getDocuments() as $document) {
$document->addField('custom_score_floatS', $this->calculateScore($document));
}
}
private function calculateScore(\ApacheSolrForTypo3\Solr\System\Solr\Document\Document $document): float
{
return match ($document->getField('type')['value'] ?? '') {
'pages' => 1.0,
'tx_news_domain_model_news' => 0.8,
default => 0.5,
};
}
}
v13 fallback (if #[AsEventListener] is not available): register in Services.yaml:
MyVendor\MyExt\EventListener\EnrichSolrDocuments:
tags:
- name: event.listener
identifier: 'my-ext/enrich-solr-documents'
10. Independent Indexer (Custom Data)
For external data or when the RecordIndexer is not sufficient:
<?php
declare(strict_types=1);
namespace MyVendor\MyExt\Indexer;
use ApacheSolrForTypo3\Solr\ConnectionManager;
use ApacheSolrForTypo3\Solr\Domain\Site\SiteRepository;
use ApacheSolrForTypo3\Solr\System\Solr\Document\Document;
final class ExternalDataIndexer
{
public function __construct(
private readonly ConnectionManager $connectionManager,
private readonly SiteRepository $siteRepository,
) {}
public function index(array $rows, int $rootPageId = 1, int $language = 0): void
{
$site = $this->siteRepository->getSiteByRootPageId($rootPageId);
$connection = $this->connectionManager->getConnectionByPageId($rootPageId, $language);
$documents = [];
foreach ($rows as $row) {
$document = new Document();
$document->setField('id', 'external_' . $row['uid']);
$document->setField('variantId', 'external_' . $row['uid']);
$document->setField('type', 'external_record');
$document->setField('appKey', 'EXT:solr');
$document->setField('access', ['r:0']);
$document->setField('site', $site->getDomain());
$document->setField('siteHash', $site->getSiteHash());
$document->setField('uid', $row['uid']);
$document->setField('pid', $rootPageId);
$document->setField('title', $row['title']);
$document->setField('content', $row['content']);
$document->setField('url', $row['url']);
$documents[] = $document;
}
$connection->getWriteService()->addDocuments($documents);
}
public function clearIndex(string $type = 'external_record'): void
{
$connections = $this->connectionManager->getAllConnections();
foreach ($connections as $connection) {
$connection->getWriteService()->deleteByType($type);
}
}
}
CLI Command Wrapper
<?php
declare(strict_types=1);
namespace MyVendor\MyExt\Command;
use MyVendor\MyExt\Indexer\ExternalDataIndexer;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;
#[AsCommand(name: 'myext:index-external', description: 'Index external data into Solr')]
final class IndexExternalCommand extends Command
{
public function __construct(
private readonly ExternalDataIndexer $indexer,
) {
parent::__construct();
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$io = new SymfonyStyle($input, $output);
$rows = $this->fetchExternalData();
$io->info(sprintf('Indexing %d records...', count($rows)));
$this->indexer->index($rows);
$io->success('Done.');
return Command::SUCCESS;
}
private function fetchExternalData(): array
{
// Implement your data fetching logic
return [];
}
}
11. LLM & Vector Search (Solr Server Native)
Apache Solr 9.8+ includes a native LLM module for semantic/vector search. This runs on the Solr server side -- EXT:solr queries the results.
graph LR
subgraph indexing [Index Time]
Text[Document text]
URP["TextToVectorUpdateProcessor"]
API1["Embedding API<br/>(OpenAI, Mistral, etc.)"]
Vector1[Dense Vector]
SolrIdx["Solr Index<br/>(DenseVectorField)"]
end
subgraph querying [Query Time]
Query[User query text]
QP["knn_text_to_vector parser"]
API2["Embedding API"]
Vector2[Query Vector]
KNN["KNN Search"]
Results[Ranked Results]
end
Text --> URP --> API1 --> Vector1 --> SolrIdx
Query --> QP --> API2 --> Vector2 --> KNN --> Results
SolrIdx -.->|similarity| KNN
Prerequisites
- Apache Solr 9.8+ with the
llm module enabled
- An external embedding API account (OpenAI, Mistral AI, Cohere, or HuggingFace)
Schema: DenseVectorField
Add to your schema (or use a custom configset):
<fieldType name="knn_vector" class="solr.DenseVectorField"
vectorDimension="1536"
similarityFunction="cosine"
knnAlgorithm="hnsw"/>
<field name="vector" type="knn_vector" indexed="true" stored="true"/>
vectorDimension must match your embedding model (e.g., OpenAI text-embedding-3-small = 1536 dimensions).
Model Configuration
Register the query parser in solrconfig.xml:
<queryParser name="knn_text_to_vector"
class="org.apache.solr.llm.textvectorisation.search.TextToVectorQParserPlugin"/>
Upload a model definition:
curl -XPUT 'http://localhost:8983/solr/core_en/schema/text-to-vector-model-store' \
--data-binary @model.json -H 'Content-type:application/json'
model.json (OpenAI example):
{
"class": "dev.langchain4j.model.openai.OpenAiEmbeddingModel",
"name": "openai-embed",
"params": {
"baseUrl": "https://api.openai.com/v1",
"apiKey": "sk-...",
"modelName": "text-embedding-3-small",
"timeout": 60,
"maxRetries": 3
}
}
Supported providers: OpenAI, Mistral AI, Cohere, HuggingFace. See LangChain4j Embedding Models for all parameters.
Indexing with Vectors
Add an update processor chain in solrconfig.xml:
<updateRequestProcessorChain name="vectorisation">
<processor class="solr.llm.textvectorisation.update.processor.TextToVectorUpdateProcessorFactory">
<str name="inputField">_text_</str>
<str name="outputField">vector</str>
<str name="model">openai-embed</str>
</processor>
<processor class="solr.RunUpdateProcessorFactory"/>
</updateRequestProcessorChain>
Two-pass strategy (recommended for production): index documents normally first, then enrich with vectors in a second pass to avoid blocking the indexing pipeline with slow API calls.
Querying
Semantic search (text in, vector out):
?q={!knn_text_to_vector model=openai-embed f=vector topK=10}customer complaints handling
Raw vector search:
?q={!knn f=vector topK=10}[0.1, 0.2, 0.3, ...]
Threshold search (all documents above similarity):
?q={!vectorSimilarity f=vector minReturn=0.7}[0.1, 0.2, 0.3, ...]
Hybrid search (BM25 + vector re-ranking):
?q=customer complaints
&rq={!rerank reRankQuery=$rqq reRankDocs=50 reRankWeight=2}
&rqq={!knn_text_to_vector model=openai-embed f=vector topK=50}customer complaints
Pre-Filtering
Combine vector search with traditional filters:
?q={!knn_text_to_vector model=openai-embed f=vector topK=10 preFilter=type:pages}search query
EXT:solr Integration
EXT:solr 13.1 has initial vector search support. For custom integration, use a PSR-14 event listener on BeforeDocumentsAreIndexedEvent to add vector data to documents via your own embedding service call.
Note: Full native vector search support in EXT:solr (Index Queue -> vector fields, Fluid templates for vector results) is still evolving. Monitor the GitHub repository for updates.
Use Cases
| Use Case | Approach |
|---|
| Smart site search | knn_text_to_vector finds semantically similar content |
| Similar content | Given a document's vector, find K nearest neighbors |
| Multilingual bridge | Embeddings can match across languages |
| FAQ matching | Match user questions to FAQ answers despite different wording |
| RAG preparation | Use Solr as retrieval layer for LLM-powered Q&A |
| File discovery | Combined with solrfal + Tika: semantic search over documents |
12. Debugging & Troubleshooting
This section is the core reference for diagnosing and fixing EXT:solr issues. If you are new to EXT:solr, start with the step-by-step guide below before jumping to the reference sections.
Step-by-Step Troubleshooting Guide (Beginner)
If search is not working and you have no idea where to start, follow these steps in order. Each step explains what you are checking, where to find it, and what the result means.
Step 1: Understand the Architecture
Before debugging, know how EXT:solr works. There are four parts that must all work:
┌─────────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 1. Connection │───▶│ 2. Indexing │───▶│ 3. Solr Core │───▶│ 4. Frontend │
│ TYPO3 ↔ Solr │ │ Queue+Worker │ │ Documents │ │ Search+Fluid │
└─────────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
- Connection: TYPO3 must know where Solr is running (host, port, core name)
- Indexing: TYPO3 must send your content (pages, news, etc.) to Solr via the Index Queue and a Scheduler task
- Solr Core: The Solr server stores documents and makes them searchable
- Frontend: The search plugin sends queries to Solr and renders results via Fluid templates
A problem at any of these four parts breaks search. The steps below check each part from left to right.
Step 2: Is Solr Reachable? (Connection Check)
Where: TYPO3 Backend → Admin Tools → Reports → Status Report
What you see: A list of status checks. Look for entries about "Solr":
- All green ✅ = Solr is reachable, connection works → go to Step 3
- Red/yellow ⚠️ = Solr is not reachable → fix connection first
If red -- things to check:
Open your site configuration file config/sites/<your-site>/config.yaml and verify these settings:
solr_enabled_read: true
solr_host_read: solr # hostname where Solr runs
solr_port_read: '8983' # port (8983 for standalone, 8984 for DDEV)
solr_scheme_read: http # http or https (DDEV uses https)
solr_path_read: / # usually just /
solr_core_read: core_en # must match the actual core name in Solr
For DDEV users:
solr_host_read: <your-project>.ddev.site
solr_port_read: '8984'
solr_scheme_read: https
Quick test from the terminal:
# DDEV: test if Solr responds
ddev exec curl -s http://solr:8983/solr/core_en/admin/ping
# Expected: {"status":"OK"}
# If "Connection refused": Solr container is not running → ddev restart
After fixing: Always click "Initialize connection" in the EXT:solr backend module (Web → Search → Overview tab).
Step 3: Is Content in the Index Queue? (Indexing Check)
Where: TYPO3 Backend → Web → Search → "Index Queue" tab
What you see: A table showing record types (pages, news, etc.) with counts.
| What you see | What it means | What to do |
|---|
| Table is empty | No content has been queued for Solr | You need to initialize the queue (see below) |
| Items with count > 0, errors = 0 | Content is queued and indexed | Go to Step 4 |
| Items with errors > 0 | Indexing failed for some records | Read the error messages (see below) |
If the queue is empty:
-
Check that EXT:solr TypoScript templates are included on the root page:
- Backend → Web → Template module → root page → "Includes" tab
- You must see "Search - Base Configuration" in the list
- If it's missing, add it: click "Include static (from extensions)" and select "Search - Base Configuration (solr)"
-
Initialize the queue:
- Go to Web → Search → "Index Queue" tab
- Select the checkboxes for the record types you want to index (e.g., "pages")
- Click "Queue selected content"
- The table should now show a count
If items have errors:
The errors column tells you what went wrong. Common errors:
| Error message | What it means | Fix |
|---|
| "Could not resolve host" | Solr server unreachable | Go back to Step 2 |
| "Document is missing mandatory uniqueKey field: id" | The document has no ID | Check your TypoScript field mapping |
| "OutOfMemoryError" | PHP or Solr ran out of memory | Increase memory_limit for the scheduler |
| "HTTP 404" | The Solr core doesn't exist | Check core name, run ddev solrctl apply |
Step 4: Have Documents Arrived in Solr? (Solr Check)
Even if the queue shows no errors, documents might not have been sent to Solr yet. The queue only fills the to-do list -- a Scheduler task actually sends them.
Check if the Scheduler task exists:
- Backend → System → Scheduler
- Look for a task called "Index Queue Worker" (class:
ApacheSolrForTypo3\Solr\Task\IndexQueueWorkerTask)
- If it doesn't exist: create it (Add task → select "Index Queue Worker" → save)
- If it exists: check "Last execution" -- has it run recently?
Run it manually now:
- Click the "play" button next to the Index Queue Worker task
Verify documents are in Solr:
Open the Solr Admin UI:
- DDEV: run
ddev launch :8984 (opens in browser)
- Production: navigate to
http://your-solr-host:8983/solr/
In Solr Admin UI:
- Select your core from the dropdown (e.g.,
core_en)
- Click "Query" in the left menu
- Leave
q as *:* (means "all documents")
- Click "Execute Query"
- Check
numFound in the response:
| numFound | What it means | What to do |
|---|
| 0 | No documents at all | Scheduler task didn't run, or indexing failed silently → enable logging (see 12.0 Layer 2 below) |
| > 0 | Documents exist in Solr | Go to Step 5 |
Useful queries to run in Solr Admin:
# How many documents per type?
q=*:*&rows=0&facet=true&facet.field=type
# Show 5 page documents with their key fields
q=*:*&fq=type:pages&rows=5&fl=uid,title,url,siteHash
# Search for a specific term
q=your search term&fl=uid,title,score
Step 5: Does the Frontend Show Results? (Frontend Check)
Where: Open the page with the search plugin in the frontend, type a search term you know exists in Solr.
| What you see | What it means | What to do |
|---|
| "Search is currently not available" | Plugin can't connect to Solr | Go back to Step 2 -- connection issue from the frontend |
| Search works, but 0 results | Query runs but finds nothing | Check site hash, access field (see below) |
| Results appear but wrong | Documents found but wrong content/order | Check field mapping, boosting (see below) |
| Results appear correctly ✅ | Everything works! | Done |
If 0 results even though Solr has documents:
The most common cause is a site hash mismatch. EXT:solr adds a siteHash to every document to prevent cross-site contamination. If the hash during indexing differs from the hash during searching, no results appear.
Check in Solr Admin:
# What siteHash values exist in the index?
q=*:*&rows=0&facet=true&facet.field=siteHash
Compare with what EXT:solr expects: open Extension Settings (Admin Tools → Settings → Extension Configuration → solr) and check siteHashStrategy. Since EXT:solr 13.0, the default is site-identifier (not domain).
If the hashes don't match: re-index (Backend → Web → Search → Index Queue → clear and re-queue all).
Other causes of 0 results:
plugin.tx_solr.search.targetPage points to wrong page → set it to the page UID containing the search pluginplugin.tx_solr.enabled is 0 somewhere in TypoScript → check for override- Access restrictions: the
access field on documents doesn't match the frontend user → test in Solr Admin with q=*:*&fl=uid,title,access
Step 6: Something Else is Wrong -- Enable Logging
If the steps above didn't solve it, enable logging to see exactly what EXT:solr does:
1. Add TypoScript logging (on the root page, dev/staging only):
plugin.tx_solr.logging {
debugOutput = 1
exceptions = 1
indexing = 1
query.rawGet = 1
query.queryString = 1
query.searchWords = 1
}
2. Write logs to a file (in config/system/additional.php):
$GLOBALS['TYPO3_CONF_VARS']['LOG']['ApacheSolrForTypo3']['Solr']['writerConfiguration'] = [
\Psr\Log\LogLevel::DEBUG => [
\TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
'logFile' => \TYPO3\CMS\Core\Core\Environment::getVarPath() . '/log/solr.log',
],
],
];
3. Watch the log file:
# DDEV
ddev exec tail -f var/log/solr.log
# Then trigger the action: run the scheduler, or do a search in the frontend
What to look for in the log:
[ERROR] lines → these tell you exactly what failedSolr raw GET: http://... → the exact URL sent to Solr (paste it in a browser to test)Response: 0 results → Solr answered but found nothing (site hash? access? wrong field?)
4. Also check: Admin Tools → Log module (filter by component "ApacheSolrForTypo3")
Step 7: Still Stuck? Escalation Path
If all six steps above didn't solve it:
- Ask in Slack: TYPO3 Slack #ext-solr -- the maintainers (dkd) are active here
- Search GitHub Issues: TYPO3-Solr/ext-solr/issues -- your problem might already be reported
- dkd support: Professional support -- paid support from the extension maintainers
- Collect info for a bug report: Solr version, EXT:solr version, PHP version, TYPO3 version, error messages from the log, Solr Admin query results
12.0 How to Get Debug Data
Before you can fix anything, you need to see what EXT:solr is doing. There are six layers of debug data, from quick checks to deep inspection:
graph TD
subgraph quick ["1. Quick Checks (no config needed)"]
Reports["TYPO3 Reports Module"]
Backend["EXT:solr Backend Module"]
SolrUI["Solr Admin UI"]
end
subgraph config ["2. Enable Debug Output"]
TSLog["TypoScript logging.*"]
FileLog["FileWriter → var/log/solr.log"]
DebugTools["EXT:solrdebugtools"]
end
subgraph deep ["3. Deep Inspection"]
SolrDebug["Solr debugQuery=true"]
DB["SQL on tx_solr_* tables"]
CLI["CLI curl to Solr API"]
end
Reports --> TSLog
Backend --> TSLog
SolrUI --> SolrDebug
TSLog --> FileLog
FileLog --> DB
DebugTools --> SolrDebug
Layer 1: Quick checks (zero configuration)
TYPO3 Reports module (Admin Tools -> Reports -> Status Report):
- Shows connection status, configset match, core availability per language
- If anything is red/yellow here, fix it before debugging further
EXT:solr backend module (Web -> Search):
- Overview tab: connection status per site and language
- Index Queue tab: record counts by type, error counts, last indexed timestamp
- Index Fields tab: all fields in the Solr schema with types and stored/indexed flags
- Stop Words / Synonyms tabs: current configuration on the Solr core
Solr Admin UI (DDEV: ddev launch :8984, Production: http://host:8983/solr/):
- Dashboard: JVM memory, Solr version, uptime
- Core Selector (dropdown): pick the core you want to inspect
- Query tab: run queries directly against the core
- Schema Browser: inspect field types, stored/indexed flags, sample values
- Analysis tab: paste text to see how Solr tokenizes and stems it
Layer 2: Enable TypoScript debug logging
Add to your root page TypoScript setup (dev/staging only):
plugin.tx_solr.logging {
debugOutput = 1
exceptions = 1
indexing = 1
indexing.indexQueueInitialization = 1
indexing.pageIndexed = 1
indexing.queue.news = 1
query.rawGet = 1
query.rawPost = 1
query.queryString = 1
query.searchWords = 1
}
| Setting | What it logs |
|---|
debugOutput | Writes debug info to the TYPO3 devlog |
exceptions | Full exception stack traces from Solr communication |
indexing | Every document sent to Solr during indexing |
indexing.indexQueueInitialization | Which tables were initialized into the queue |
indexing.pageIndexed | Each page after it was indexed (URL, fields, response) |
indexing.queue.<name> | Per-config logging (e.g., queue.news, queue.events) |
query.rawGet | The exact HTTP GET URL sent to Solr |
query.rawPost | POST body sent to Solr (for complex queries) |
query.queryString | The parsed Solr query string |
query.searchWords | The user's search input after processing |
Where does the output go? By default, to the TYPO3 logging system. To get a file you can tail -f:
// config/system/additional.php
$GLOBALS['TYPO3_CONF_VARS']['LOG']['ApacheSolrForTypo3']['Solr']['writerConfiguration'] = [
\Psr\Log\LogLevel::DEBUG => [
\TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
'logFile' => \TYPO3\CMS\Core\Core\Environment::getVarPath() . '/log/solr.log',
],
],
];
Then watch live:
# DDEV
ddev exec tail -f var/log/solr.log
# Standalone
tail -f /var/www/html/var/log/solr.log
Also check the TYPO3 system log: Admin Tools -> Log module, filter by component ApacheSolrForTypo3.
Layer 3: Solr debugQuery (score explanation)
In Solr Admin UI -> Query tab, add debugQuery=true to see why a document ranks where it does:
q=typo3 solr&debugQuery=true&fl=uid,title,score
The response includes a debug section:
{
"debug": {
"rawquerystring": "typo3 solr",
"querystring": "typo3 solr",
"parsedquery": "(title:typo3 | content:typo3) (title:solr | content:solr)",
"QParser": "ExtendedDismaxQParser",
"explain": {
"4f547484...": "\n7.256 = sum of:\n 3.628 = weight(title:typo3) ...\n 3.628 = weight(title:solr) ..."
},
"timing": {
"time": 2.0,
"prepare": { "time": 1.0 },
"process": { "time": 1.0 }
}
}
}
Key fields in the debug response:
| Field | What it tells you |
|---|
parsedquery | How Solr interpreted your search terms (which fields, operators) |
explain | Per-document score breakdown: which fields matched, TF-IDF/BM25 weights |
timing | Query execution time per phase (prepare, process) |
rawquerystring | The original query before parsing |
Reading the explain output: Each line shows a score component. Higher = more relevant. Look for:
- Which fields contribute most (title vs content)
- Boost values being applied
- Whether coord (coordination) penalizes partial matches
Layer 4: EXT:solrdebugtools (funding extension)
EXT:solrdebugtools adds visual debugging to the frontend:
- Debug\Query ViewHelper: shows the Solr query, parsed query, and timing in the frontend
- Explain display: per-result score breakdown as pie chart
- Query parameters: see all parameters sent to Solr
Add to your Fluid template during development:
<solrdebug:query resultSet="{resultSet}" />
This renders a debug panel directly in the search results page showing the full Solr request and response.
Layer 5: CLI curl to Solr API
Bypass TYPO3 entirely and talk to Solr directly:
# Ping (is Solr alive?)
ddev exec curl -s http://solr:8983/solr/core_en/admin/ping | python3 -m json.tool
# Total document count
ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=*:*&rows=0' | python3 -m json.tool
# Search with debug
ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=test&debugQuery=true&fl=uid,title,score&wt=json' | python3 -m json.tool
# Check a specific document by uid
ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=uid:42&fl=*' | python3 -m json.tool
# List all field names in the index
ddev exec curl -s 'http://solr:8983/solr/core_en/admin/luke?numTerms=0&wt=json' | python3 -m json.tool | grep '"name"'
# Document count by type
ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=*:*&rows=0&facet=true&facet.field=type' | python3 -m json.tool
# Check what siteHash values exist
ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=*:*&rows=0&facet=true&facet.field=siteHash' | python3 -m json.tool
# Analyze how a term is tokenized (for field type "text")
ddev exec curl -s 'http://solr:8983/solr/core_en/analysis/field?analysis.fieldname=content&analysis.fieldvalue=TYPO3+Content+Management&wt=json' | python3 -m json.tool
From host (replace ddev exec curl -s http://solr:8983 with curl -sk https://<project>.ddev.site:8984).
Layer 6: Database-level inspection
Query the TYPO3 database to see what EXT:solr thinks the state is:
-- How many items per type/config, and how many have errors?
SELECT item_type, indexing_configuration,
COUNT(*) as total,
SUM(CASE WHEN indexed > 0 THEN 1 ELSE 0 END) as indexed,
SUM(CASE WHEN errors != '' THEN 1 ELSE 0 END) as errors,
SUM(CASE WHEN changed > indexed THEN 1 ELSE 0 END) as stale
FROM tx_solr_indexqueue_item
GROUP BY item_type, indexing_configuration;
-- Show the actual error messages
SELECT uid, item_type, item_uid, LEFT(errors, 200) as error_preview
FROM tx_solr_indexqueue_item
WHERE errors != ''
ORDER BY uid DESC LIMIT 20;
-- When was the last successful indexing run?
SELECT MAX(FROM_UNIXTIME(indexed)) as last_indexed
FROM tx_solr_indexqueue_item
WHERE indexed > 0;
-- What is the site hash stored for a specific page?
SELECT uid, title, slug
FROM pages
WHERE uid = 1;
-- Then check: the site hash comes from the site identifier in config.yaml
Putting it all together: Debug workflow
graph TD
Problem["Something's wrong"]
Problem --> Reports["1. Check Reports module"]
Reports -->|Red| Connection["Fix connection (12.2)"]
Reports -->|Green| Queue["2. Check Index Queue in backend module"]
Queue -->|Empty| Init["Initialize queue, check TypoScript"]
Queue -->|Errors| SQL["3. Read error messages from DB"]
Queue -->|OK| SolrAdmin["4. Query Solr Admin directly"]
SolrAdmin -->|No docs| Scheduler["Run scheduler, check indexing log"]
SolrAdmin -->|Docs exist| Frontend["5. Check frontend TypoScript"]
Frontend -->|No results| TS["Enable query logging, check siteHash"]
Frontend -->|Wrong results| Debug["6. debugQuery=true, check scoring"]
Scheduler --> Log["Enable indexing logging, tail solr.log"]
12.1 Where to Start: Diagnostic Flowchart
graph TD
Start["Problem with Solr?"]
Start --> A{"Reports module:<br/>all green?"}
A -->|No| Fix1["Fix connection config<br/>(see 12.2)"]
A -->|Yes| B{"Index Queue:<br/>items present?"}
B -->|No| Fix2["Initialize queue<br/>(see 12.3)"]
B -->|Yes| C{"Items have<br/>errors?"}
C -->|Yes| Fix3["Check error messages<br/>(see 12.3)"]
C -->|No| D{"Solr Admin:<br/>documents exist?"}
D -->|No| Fix4["Run scheduler worker<br/>(see 12.3)"]
D -->|Yes| E{"Frontend shows<br/>results?"}
E -->|No| Fix5["Check TypoScript,<br/>site hash (see 12.4)"]
E -->|Yes| Done["Working!"]
Step 1: Check TYPO3 Reports module (Admin Tools -> Reports -> Status Report). All Solr-related checks must be green.
Step 2: Open Solr Admin UI. DDEV: ddev launch :8984. Production: https://your-host:8983/solr/.
Step 3: EXT:solr backend module -> "Index Queue" tab. Are items queued? Any errors?
12.2 Connection Problems
"Search is currently not available" -- full checklist:
- Verify site config values:
solr_host_read, solr_port_read, solr_scheme_read, solr_path_read
- Click "Initialize connection" in the EXT:solr backend module after ANY config change
- Test from CLI:
# Inside DDEV container
ddev exec curl -s http://solr:8983/solr/core_en/admin/ping
# From host
curl -sk https://<project>.ddev.site:8984/solr/core_en/admin/ping
- DDEV networking: Inside the container, Solr is reachable at hostname
solr on port 8983. From the host, use <project>.ddev.site:8984 with HTTPS.
- Firewall: Ensure port 8983 (or 8984 for DDEV) is open
- HTTPS: DDEV uses self-signed certificates. Use
solr_scheme_read: https with DDEV.
12.3 Indexing Problems
Nothing in Index Queue
- TypoScript not loaded: Check the Template module on the root page. EXT:solr static templates must be included.
- Queue not initialized: Backend module -> "Index Queue" tab -> select record types -> click "Queue selected content"
- Missing config:
plugin.tx_solr.index.queue.[table] = 1 must exist for each table
- Records outside siteroot: Set
additionalPageIds and enable "tracking of records outside siteroot" in Extension Settings
Items in Queue but Not Indexed
- Scheduler not running: A "Index Queue Worker" scheduler task must be configured and executing
- Check errors: Inspect the
errors column:
SELECT item_type, errors, COUNT(*) as cnt
FROM tx_solr_indexqueue_item
WHERE errors != ''
GROUP BY item_type, errors;
- Forced webroot: If TYPO3 cannot auto-detect the web root (CLI context), configure "Forced webroot" in the scheduler task settings
- Memory: Large content can exceed PHP
memory_limit. Increase for the scheduler process.
Items Indexed but Wrong/Missing Content
- Check the actual document in Solr Admin UI:
q=*:*&fq=type:tx_news_domain_model_news&rows=5&fl=uid,title,content,url,siteHash
- Field mapping: Verify
plugin.tx_solr.index.queue.[table].fields TypoScript matches your Solr schema fields
- HTML in content: Use
SOLR_CONTENT to strip HTML from RTE fields
- Relations empty: Use
SOLR_RELATION with multiValue = 1 for category/tag fields
Re-indexing
- Soft re-index: Backend module -> clear queue -> re-queue -> run scheduler task
- Force re-index: Scheduler task "Force Re-Indexing of a site" for specific configurations
- Nuclear option (DDEV only):
TRUNCATE tx_solr_indexqueue_item; then re-initialize via backend module
12.4 Search / Query Problems
No Results in Frontend
graph LR
Plugin["Search Plugin<br/>(Fluid)"] --> TS["TypoScript Config"]
TS --> SolrQ["Solr Query<br/>(HTTP GET)"]
SolrQ --> Response["Solr Response<br/>(JSON)"]
Response --> Render["Fluid Rendering"]
Wrong Results / Bad Relevance
- debugQuery: In Solr Admin, run
q=YOUR_TERM&debugQuery=true to see score breakdowns
- EXT:solrdebugtools: Install for Debug\Query ViewHelper, Explain functionality, and score pie charts
- Boosting: Configure field weights:
plugin.tx_solr.search.query {
boostFunction = recip(ms(NOW,created),3.16e-11,1,1)
boostQuery = type:pages^2.0
}
Facets Not Showing
plugin.tx_solr.search.faceting = 1 missing- Field not indexed (check dynamic field suffix matches schema)
initializeWithEmptyQuery = 1 needed to show facets before any search- Facet field has zero values in indexed documents
12.5 Logging Deep Dive
For the full logging setup (TypoScript config, FileWriter, tail -f), see 12.0 Layer 2 above.
Selective logging per Index Queue config:
You can enable logging for just one config to reduce noise:
plugin.tx_solr.logging {
indexing = 0
indexing.queue.events = 1
}
This logs only the "events" queue processing, not "news" or "pages".
What the indexing log contains per document:
[DEBUG] Indexing document: tx_news_domain_model_news:42
Fields: title=My Event, content=...(truncated), url=/events/my-event
Solr response: {"responseHeader":{"status":0,"QTime":3}}
If indexing fails, you'll see the Solr error response:
[ERROR] Indexing failed for tx_news_domain_model_news:42
Error: Document is missing mandatory uniqueKey field: id
What the query log contains:
[DEBUG] Solr query: q=test+search&fq=siteHash:abc123&fl=*,score
[DEBUG] Solr raw GET: http://solr:8983/solr/core_en/select?q=test+search&...
[DEBUG] Search words: ["test", "search"]
[DEBUG] Response: 15 results in 3ms
Warning: Disable logging on production. Log data grows quickly and impacts performance. Remove the plugin.tx_solr.logging config and the writerConfiguration from additional.php.
12.6 Solr Admin UI as Debugging Tool
See 12.0 Layer 5 for CLI curl equivalents of all these queries.
Key diagnostic queries (run in Solr Admin -> Query tab):
| Query | Purpose |
|---|
q=*:*&rows=0 | Total document count |
q=*:*&fq=type:pages&rows=5&fl=uid,title,url,siteHash | Check indexed pages |
q=*:*&fq=type:tx_news_domain_model_news&fl=uid,title,content | Check custom records |
q=YOUR_TERM&debugQuery=true | Score explanation (see 12.0 Layer 3 for reading the output) |
q=*:*&facet=true&facet.field=type&rows=0 | Document type distribution |
q=*:*&fq=siteHash:YOUR_HASH&rows=0 | Documents per site hash |
Additional useful queries:
# Find a specific record by UID and type
q=*:*&fq=uid:42&fq=type:tx_news_domain_model_news&fl=*
# Check which fields exist on a document (all fields)
q=*:*&rows=1&fl=*
# Compare what two configs indexed
q=*:*&fq=indexing_configuration:news&rows=0
q=*:*&fq=indexing_configuration:events&rows=0
# Find documents with empty content
q=*:*&fq=-content:[* TO *]&fl=uid,title,type
# Check the access field (frontend user restrictions)
q=*:*&fl=uid,title,access&rows=10
Core Admin: Reload a core after schema changes (Core Admin -> Reload button, or via API: curl http://solr:8983/solr/admin/cores?action=RELOAD&core=core_en).
Analysis screen: Test how text is tokenized and stemmed. In Solr Admin -> Analysis, select the field type (e.g., text), paste text in the "Field Value (Index)" box, and click "Analyse Values". This shows every processing step: char filters, tokenizer, token filters (lowercase, stop words, stemming).
12.7 Database-Level Debugging
See 12.0 Layer 6 for the complete SQL query cookbook.
Quick reference:
-- Overview: what's in the queue?
SELECT item_type, indexing_configuration,
COUNT(*) as total,
SUM(CASE WHEN errors != '' THEN 1 ELSE 0 END) as errors
FROM tx_solr_indexqueue_item
GROUP BY item_type, indexing_configuration;
-- What went wrong?
SELECT uid, item_type, item_uid, errors, changed, indexed
FROM tx_solr_indexqueue_item
WHERE errors != ''
LIMIT 20;
-- Event queue (delayed monitoring mode)
SELECT * FROM tx_solr_eventqueue_item
ORDER BY tstamp DESC LIMIT 20;
-- Items that need re-indexing
SELECT uid, item_type, item_uid, changed, indexed
FROM tx_solr_indexqueue_item
WHERE changed > indexed
LIMIT 20;
-- Reset errors to retry indexing
UPDATE tx_solr_indexqueue_item SET errors = '' WHERE errors != '';
12.8 Common Issues Quick Reference
| Symptom | Likely Cause | Fix |
|---|
| "Search is currently not available" | Solr connection misconfigured | Check site config, initialize connection |
| No results for any query | Site hash mismatch | Check siteHashStrategy, re-index |
| Empty Index Queue | TypoScript not loaded on root page | Include EXT:solr static templates |
| Queue items never indexed | Scheduler task not running | Create "Index Queue Worker" task |
| Items in queue with errors | Indexing failure (memory, URL) | Check errors column in DB |
| Facets not visible | faceting = 0 or empty field | Enable faceting, check field has values |
| Suggest not working | suggest = 0 or jQuery missing | Enable suggest, check JS includes |
| Wrong content in results | Field mapping incorrect | Fix TypoScript fields config |
| Access-restricted pages missing | linkAccessRestrictedPages not set | Add config.typolinkLinkAccessRestrictedPages = 1 |
| URL generation fails for records | detailPid not configured | Set the correct detail page ID |
Docker: permission denied on /var/solr | Volume ownership wrong | Ensure UID 8983 owns the volume |
| DDEV: port 8984 not reachable | Addon not installed or Solr down | ddev add-on get ddev/ddev-typo3-solr && ddev restart |
| Configset version mismatch | Wrong configset deployed | Redeploy matching ext_solr_13_1_0 |
| Jar loading error (Solr 9.8+) | CVE-2025-24814 migration needed | Move typo3lib/ to server root, or pull Docker 13.0.1+ |
| Tika: connection timeout | Tika Server not running or wrong port | Check Docker container, test connection in extension settings |
| Language core missing | No core for language |
13. Testing
Functional Test Setup
<?php
declare(strict_types=1);
namespace MyVendor\MyExt\Tests\Functional;
use ApacheSolrForTypo3\Solr\Tests\Integration\IntegrationTestCase;
final class CustomIndexingTest extends IntegrationTestCase
{
protected array $testExtensionsToLoad = [
'apache-solr-for-typo3/solr',
'my-vendor/my-ext',
];
public function testNewsRecordIsIndexed(): void
{
$this->importCSVDataSet(__DIR__ . '/Fixtures/news_records.csv');
$this->indexQueue('news');
$searchResult = $this->searchInSolr('test news title');
self::assertGreaterThan(0, $searchResult->getResultCount());
}
}
Testing Custom Event Listeners
<?php
declare(strict_types=1);
namespace MyVendor\MyExt\Tests\Unit\EventListener;
use ApacheSolrForTypo3\Solr\Event\Indexing\BeforeDocumentsAreIndexedEvent;
use ApacheSolrForTypo3\Solr\System\Solr\Document\Document;
use MyVendor\MyExt\EventListener\EnrichSolrDocuments;
use PHPUnit\Framework\TestCase;
final class EnrichSolrDocumentsTest extends TestCase
{
public function testCustomScoreIsAdded(): void
{
$document = new Document();
$document->setField('type', 'pages');
$event = $this->createMock(BeforeDocumentsAreIndexedEvent::class);
$event->method('getDocuments')->willReturn([$document]);
$listener = new EnrichSolrDocuments();
$listener($event);
self::assertNotNull($document->getField('custom_score_floatS'));
}
}
14. Best Practices
Production Checklist
Security
- Solr must never be publicly accessible. Use firewall rules or bind to
127.0.0.1
- Use a reverse proxy (nginx/Apache) with authentication if remote access is needed
- Monitor Apache Solr security advisories
- Keep Tika Server updated (CVE-2025-54988: requires 3.2.2+)
Performance
- Commit strategy: Use
autoSoftCommit (1-5 seconds) for near-real-time, autoCommit (15-60 seconds) for durability
- Cache warming: Configure
newSearcher and firstSearcher events in solrconfig.xml
- Segment merging: Monitor segment count in Solr Admin, consider
optimize during off-peak
Multi-Site / Multi-Language
- One Solr core per language (e.g.,
core_en, core_de) with language-specific schema
- Each TYPO3 site configures its own Solr connection in site config YAML
- Use
siteHash to isolate documents per site
Environment Configuration
Use helhum/dotenv-connector to manage Solr credentials per environment:
.env file per environment (local, staging, production) with SOLR_HOST, SOLR_PORT, etc.- Never hardcode connection details in site config YAML committed to VCS
- Commit
.env.example with placeholder values
15. Database Structure
| Table | Purpose |
|---|
tx_solr_indexqueue_item | Items queued for indexing (type, uid, errors, timestamps) |
tx_solr_indexqueue_indexing_property | Additional indexing properties per queue item |
tx_solr_last_searches | Recently executed search terms |
tx_solr_statistics | Search statistics (terms, result counts, timestamps) |
tx_solr_eventqueue_item | Event queue for delayed monitoring mode |
Key columns in tx_solr_indexqueue_item:
| Column | Type | Purpose |
|---|
item_type | varchar | Table name (e.g., pages, tx_news_domain_model_news) |
item_uid | int | Record UID |
indexing_configuration | varchar | TypoScript configuration name |
changed | int | Timestamp when record was last changed |
indexed | int | Timestamp when record was last indexed |
errors | text | Error message from last indexing attempt |
FAQ / Common Recipes
One Table, Two Index Configs (e.g. News + Events from EXT:news)
A common pattern: EXT:news is installed once but serves two purposes -- classic news articles and an event calendar (or product announcements, press releases, etc.). You want them as separate facet values in search.
Step 1: Two Index Queue configurations for the same table
Use additionalWhereClause to split records by category, type field, or sysfolder PID:
plugin.tx_solr.index.queue {
# Config 1: Classic news articles
news = 1
news {
type = tx_news_domain_model_news
additionalWhereClause = categories.uid IN (1,2,3)
fields {
title = title
content = SOLR_CONTENT
content.cObject = COA
content.cObject {
10 = TEXT
10.field = bodytext
}
category_stringM = SOLR_RELATION
category_stringM {
localField = categories
multiValue = 1
}
url = TEXT
url {
typolink.parameter = {$plugin.tx_news.settings.detailPid}
typolink.additionalParams = &tx_news_pi1[controller]=News&tx_news_pi1[action]=detail&tx_news_pi1[news]={field:uid}
typolink.additionalParams.insertData = 1
typolink.returnLast = url
}
# Custom field to distinguish in facets
newstype_stringS = TEXT
newstype_stringS.value = News
}
}
# Config 2: Events (same table, different records)
events = 1
events {
type = tx_news_domain_model_news
additionalWhereClause = categories.uid IN (4,5,6)
fields {
title = title
content = SOLR_CONTENT
content.cObject = COA
content.cObject {
10 = TEXT
10.field = bodytext
}
category_stringM = SOLR_RELATION
category_stringM {
localField = categories
multiValue = 1
}
# Event-specific fields
eventdate_dateS = datetime
eventlocation_stringS = TEXT
eventlocation_stringS {
field = teaser
}
url = TEXT
url {
typolink.parameter = {$plugin.tx_news.settings.detailPid}
typolink.additionalParams = &tx_news_pi1[controller]=News&tx_news_pi1[action]=detail&tx_news_pi1[news]={field:uid}
typolink.additionalParams.insertData = 1
typolink.returnLast = url
}
newstype_stringS = TEXT
newstype_stringS.value = Event
}
}
}
Alternative split strategies (use only one):
| Strategy | additionalWhereClause | When to use |
|---|
| By category | categories.uid IN (4,5,6) | Different category trees for news vs events |
| By sysfolder | pid IN (50,51) | News and events stored in separate sysfolders |
| By type field | tx_news_domain_model_news.type = 1 | EXT:news type field distinguishes record types |
| By tag | tags.uid = 10 | Tagged with a specific tag |
Step 2: Facet on the custom field
plugin.tx_solr.search.faceting {
facets {
newstype {
label = Content Type
field = newstype_stringS
}
}
}
This shows "News (42)" and "Event (15)" as facet options.
Step 3: Initialize both queue configs
In the EXT:solr backend module -> Index Queue tab, both "news" and "events" appear as separate indexing configurations. Select both and click "Queue selected content".
How it works internally: Each config creates its own tx_solr_indexqueue_item entries with indexing_configuration = 'news' or indexing_configuration = 'events'. The Scheduler worker processes both. In Solr, the documents have type = tx_news_domain_model_news (the table name) but differ in the newstype_stringS field.
Tip: If you want the Solr type field itself to differ (e.g., type = news vs type = events), you can override it in the fields config: type = TEXT / type.value = events. Be aware this affects other type-based filtering.
Different Detail Page URLs per Config
When news and events have separate detail pages:
plugin.tx_solr.index.queue.news.fields.url {
typolink.parameter = 42
# ...
}
plugin.tx_solr.index.queue.events.fields.url {
typolink.parameter = 55
# ...
}
Three or More Configs from One Table
The pattern scales -- you can create as many Index Queue configs as needed for the same table. Each gets its own name, additionalWhereClause, field mappings, and detail page URL.
Related Skills
- typo3-datahandler: Database operations that trigger Solr indexing
- typo3-seo: SEO configuration that complements Solr search
- ai-search-optimization: AEO/GEO for AI search visibility
- typo3-content-blocks: Content Elements that can be indexed
- typo3-testing: Testing patterns for TYPO3 extensions
References
Official Documentation
GitHub Repositories
Apache Solr Server
Commercial & Hosting
DDEV
Mittwald
Environment Config
Community
Blogs & Tutorials
Credits & Attribution
- dkd Internet Service GmbH for developing and maintaining EXT:solr, EXT:tika, and the TYPO3-Solr ecosystem
- Apache Software Foundation for Apache Solr and Apache Tika
- b13 for maintaining the ddev-typo3-solr addon
- Helmut Hummel (helhum) for dotenv-connector
- Mittwald for managed Solr hosting documentation
