# Typo3 Solr > 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. - Skill: `tools-only/typo3-solr` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds add tools-only/typo3-solr` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/typo3-solr/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/tools-only/typo3-solr --- # 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: 1. [EXT:solr Documentation](https://docs.typo3.org/p/apache-solr-for-typo3/solr/main/en-us/) 2. [EXT:tika Documentation](https://docs.typo3.org/p/apache-solr-for-typo3/tika/main/en-us/) 3. [Version Matrix](https://docs.typo3.org/p/apache-solr-for-typo3/solr/main/en-us/Appendix/VersionMatrix.html) 4. [GitHub: TYPO3-Solr/ext-solr](https://github.com/TYPO3-Solr/ext-solr) 5. [GitHub: v14 dev branch](https://github.com/TYPO3-Solr/ext-solr/tree/task/14LTS_compatibility) 6. [Apache Solr Reference Guide](https://solr.apache.org/guide/solr/latest/) 7. [Solr Dense Vector Search](https://solr.apache.org/guide/solr/latest/query-guide/dense-vector-search.html) 8. [Solr Text to Vector (LLM)](https://solr.apache.org/guide/solr/latest/query-guide/text-to-vector.html) 9. [typo3-solr.com](https://www.typo3-solr.com/) 10. [hosted-solr.com](https://hosted-solr.com/en/) 11. [ddev-typo3-solr](https://github.com/ddev/ddev-typo3-solr) 12. [Mittwald Solr Docs](https://developer.mittwald.de/docs/v2/platform/databases/solr/) 13. [helhum/dotenv-connector](https://github.com/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. ```mermaid 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 ```mermaid 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`](https://github.com/TYPO3-Solr/ext-solr/tree/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:** ```bash 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 ```bash composer require apache-solr-for-typo3/solr ``` ### DDEV Setup The recommended local development setup uses the [ddev-typo3-solr](https://github.com/ddev/ddev-typo3-solr) addon: ```bash ddev add-on get ddev/ddev-typo3-solr ddev restart ``` Configure `.ddev/typo3-solr/config.yaml`: ```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`: ```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) ```yaml 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: ```bash 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: ```bash 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: ```hcl 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: ```bash mw container port-forward --port 8983 ``` ### Managed Hosting: hosted-solr.com [hosted-solr.com](https://hosted-solr.com/en/) 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//config.yaml`: ```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: ```yaml solr_host_read: .ddev.site solr_port_read: '8984' solr_scheme_read: https ``` ### Environment Configuration (helhum/dotenv-connector) Never hardcode Solr connection details. Use [helhum/dotenv-connector](https://github.com/helhum/dotenv-connector) for per-environment configuration: ```bash composer require helhum/dotenv-connector ``` `.env` (gitignored): ```env 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): ```env 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. ```mermaid graph TD Question{"Do you index files?
(PDF, DOCX, XLSX)"} Question -->|Yes| NeedTika[Install EXT:tika + EXT:solrfal] Question -->|No| SkipTika[Skip -- EXT:solr handles
pages and records natively] NeedTika --> TikaServer["Run Tika Server 3.2.2+
(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](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](https://docs.typo3.org/p/apache-solr-for-typo3/solr/main/en-us/Appendix/DynamicFieldTypes.html) ### 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. ```mermaid 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: ```typoscript 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: ```typoscript 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 ```typoscript plugin.tx_solr { enabled = 1 search { targetPage = 42 initializeWithEmptyQuery = 1 showResultsOfInitialEmptyQuery = 0 trustedFields = url keepExistingParametersForNewSearches = 1 } } ``` ### Faceting ```typoscript 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 ```typoscript 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](SKILL-FRONTEND.md). ### Sorting, Highlighting, Spellcheck ```typoscript 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 = | } } spellchecking = 1 } ``` ### Route Enhancers SEO-friendly search URLs: ```yaml 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 ```typoscript 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 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`: ```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 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 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. ```mermaid graph LR subgraph indexing [Index Time] Text[Document text] URP["TextToVectorUpdateProcessor"] API1["Embedding API
(OpenAI, Mistral, etc.)"] Vector1[Dense Vector] SolrIdx["Solr Index
(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): ```xml ``` `vectorDimension` must match your embedding model (e.g., OpenAI `text-embedding-3-small` = 1536 dimensions). ### Model Configuration Register the query parser in `solrconfig.xml`: ```xml ``` Upload a model definition: ```bash 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): ```json { "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](https://docs.langchain4j.dev/category/embedding-models) for all parameters. ### Indexing with Vectors Add an update processor chain in `solrconfig.xml`: ```xml _text_ vector openai-embed ``` **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](https://github.com/TYPO3-Solr/ext-solr) 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//config.yaml` and verify these settings: ```yaml 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:** ```yaml solr_host_read: .ddev.site solr_port_read: '8984' solr_scheme_read: https ``` **Quick test from the terminal:** ```bash # 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:** 1. 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)" 2. 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: 1. Select your core from the dropdown (e.g., `core_en`) 2. Click "Query" in the left menu 3. Leave `q` as `*:*` (means "all documents") 4. Click "Execute Query" 5. 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 plugin - `plugin.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): ```typoscript 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`): ```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:** ```bash # 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 failed - `Solr 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: 1. **Ask in Slack:** [TYPO3 Slack #ext-solr](https://typo3.slack.com/messages/ext-solr/) -- the maintainers (dkd) are active here 2. **Search GitHub Issues:** [TYPO3-Solr/ext-solr/issues](https://github.com/TYPO3-Solr/ext-solr/issues) -- your problem might already be reported 3. **dkd support:** [Professional support](https://www.dkd.de/en/products/solr-enterprise-search/) -- paid support from the extension maintainers 4. **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: ```mermaid 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["SQ …(truncated)