> ## Documentation Index > Fetch the complete documentation index at: https://nikita-shkoda.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Quick reference for common issues across joins, grouping, presets, curation, CLI, DX, schema, indexer, testing, observability, and deletion. Quick reference for common issues. Each section links to deeper docs. Related: Observability, CLI, Testing ## Joins * Missing or invalid association name * Ensure you declared it on the model with belongs\_to :name, has\_one :name, or has\_many :name * See Joins → DSL * Joined fields not appearing in selection * Use nested include fields and prefix joined fields with \$assoc.field * See Field selection ## Grouping * group\_limit ignored * Provide a positive integer; omitted when nil * See Grouping → Mapping * Unexpected missing‑values behavior * Set missing\_values: true explicitly * See Grouping → State → Params ## Presets * Defaults not applied * Confirm default\_preset on the model and presets.enabled * See Presets → Config & Default * :lock mode not locking as expected * Check locked\_domains normalization and compiler pruning * See Presets → Modes ## Curation * Hidden IDs still visible * Ensure filter\_curated\_hits is set when you want hidden hits excluded * See Curation → DSL * Order of pinned hits unstable * Pin order is first‑occurrence; avoid duplicates * See Curation → Inspect/explain ## CLI * Task arguments parsed incorrectly * Quote args and avoid spaces inside brackets * See CLI → Usage * doctor exits with 1 * Run with VERBOSE=1 or FORMAT=json for details * See CLI → Doctor flow ## DX * to\_curl shows API key * Keys are redacted; update to latest, or file an issue with a snippet * See DX * dry\_run! performs I/O * dry\_run! compiles only; check for accidental client calls * See DX → Helpers ## Schema * Drift not detected * Use aliases correctly; compare compiled vs active physical * See Schema → Diff * Rollback unavailable * Retention may be insufficient; ensure previous physical retained * See Schema → API * Alias not swapped after apply * IndexationAborted prevented the swap because indexing returned a non-ok status; the new physical was auto-deleted * Fix import errors and retry * See Schema → Failed indexation safety * Orphaned physical collections accumulating * Since v30.1.6.14, failed/interrupted applies auto-clean the new physical. For older orphans, run SearchEngine::Schema.prune\_orphans! or rails 'search\_engine:schema:prune\_orphans' * See Schema → Orphan pruning ## Indexer * 413 Payload Too Large * Batches split recursively; reduce batch\_size * See Indexer → Retries & backoff * Memory spikes * Ensure streaming JSONL and avoid materializing large arrays * See Indexer → Memory notes * PartitionTimeout during parallel imports * The pool exceeded its graceful-shutdown timeout; some partitions were not processed * Check for slow partitions or increase timeout\_ms * See Indexer → Parallel batch processing ## Testing * Stub not capturing calls * Ensure SearchEngine.config.client = SearchEngine::Test::StubClient.new * Explicit `SearchEngine.config.client` always takes precedence over offline mode * See Testing → Quick start * Test mode not working as expected * Verify `test_mode` is enabled: `SearchEngine.config.test_mode?` should return `true` in test environment * Check environment: `Rails.env.test?` or `RACK_ENV=test` enables test mode automatically * Override via `SEARCH_ENGINE_TEST_MODE=1` or `SEARCH_ENGINE_OFFLINE=1` (legacy alias) * Use `SearchEngine.client` to access the configured client instance * Note: if `SearchEngine.config.client` is explicitly set, it always wins * See Testing → Test mode ## Observability * Missing events * Wrap calls with instrumentation helpers and enable subscriber * See Observability → Events * Too much PII in logs * Redaction rules mask secrets and filter literals; use params\_preview * See Observability → Redaction rules ## Deletion * No effect / deleted 0 docs * Verify into: points to the intended physical (or rely on alias) * Ensure filter is correct; try rel.dry\_run! first to preview * See Deletion * Empty input error * delete\_by requires a non-blank String or a non-empty Hash * See Deletion → Model-level * Model.cleanup or index:delete\_stale skipped * Ensure you declared stale rules inside index; otherwise cleanup logs a skip and returns 0 * Remember rules are OR‑ed; verify at least one resolves to a non‑empty filter for the given partition ## Error Reference The gem provides a structured error hierarchy under `SearchEngine::Errors`. | Error | Description | Action | | ----------------------- | -------------------------------------------------------- | ------------------------------------------------------ | | `Timeout` | Request exceeded `timeout_ms`. | Check network or increase timeout. | | `Connection` | DNS/Socket failure. | Check host availability. | | `Api` | Non-2xx response from Typesense. | Check `error.status` and `error.body`. | | `InvalidParams` | Missing or invalid inputs. | Fix arguments provided to method. | | `InvalidField` | Field not in schema (and strict mode on). | Add field to schema or disable `strict_unknown_keys`. | | `UnknownField` | Field referenced in selection not declared on model. | Add attribute declaration or fix typo. | | `InvalidOperator` | Operator not recognized by query parser. | Use supported operators (see Query DSL). | | `InvalidType` | Value cannot be coerced to declared type. | Fix value type or enable coercions. | | `InvalidSelection` | Materializer requests fields not permitted by selection. | Adjust relation's `select`/`exclude` or materializer. | | `MissingField` | Hydration missing required field. | Ensure API returns field or mark optional. | | `ConflictingSelection` | Selection inputs are malformed or ambiguous. | Normalize selection inputs. | | `InvalidGroup` | Grouping DSL used with invalid inputs. | Fix field names, limits, or missing\_values. | | `UnsupportedGroupField` | Grouping references joined/path fields. | Use base fields only for grouping. | | `HitLimitExceeded` | Result count > `max` validation. | Narrow query or increase limit. | | `IndexationAborted` | Indexing returned non-ok status during `Schema.apply!`. | Inspect new physical for errors; alias swap prevented. | | `PartitionTimeout` | Parallel pool exceeded graceful-shutdown timeout. | Check slow partitions or increase timeout. |