Apache Solr Documentation

6.5 Ref Guide (PDF Download)
Solr Tutorial
Solr Community Wiki

Older Versions of this Guide (PDF)

Ref Guide Topics


*** As of June 2017, the latest Solr Ref Guide is located at https://lucene.apache.org/solr/guide ***

Please note comments on these pages have now been disabled for all users.

Skip to end of metadata
Go to start of metadata

The solrconfig.xml file is the configuration file with the most parameters affecting Solr itself. While configuring Solr, you'll work with solrconfig.xml often, either directly or via the Config API to create "Configuration Overlays" (configoverlay.json) to override the values in solrconfig.xml.

In solrconfig.xml, you configure important features such as:

  • request handlers, which process the requests to Solr, such as requests to add documents to the index or requests to return results for a query
  • listeners, processes that "listen" for particular query-related events; listeners can be used to trigger the execution of special code, such as invoking some common queries to warm-up caches
  • the Request Dispatcher for managing HTTP communications
  • the Admin Web interface

The solrconfig.xml file is located in the conf/ directory for each collection. Several well-commented example files can be found in the server/solr/configsets/ directories demonstrating best practices for many different types of installations.

We've covered the options in the following sections:

Substituting Properties in Solr Config Files

Solr supports variable substitution of property values in config files, which allows runtime specification of various configuration options in solrconfig.xml. The syntax is ${propertyname[:option default value]}. This allows defining a default that can be overridden when Solr is launched. If a default value is not specified, then the property must be specified at runtime or the configuration file will generate an error when parsed.

There are multiple methods for specifying properties that can be used in configuration files.  Of those below, strongly consider "config overlay" as the preferred approach, as it stays local to the config set and because it's easy to modify.

JVM System Properties

Any JVM System properties, usually specified using the -D flag when starting the JVM, can be used as variables in any XML configuration file in Solr.

For example, in the sample solrconfig.xml files, you will see this value which defines the locking type to use:

Which means the lock type defaults to "native" but when starting Solr, you could override this using a JVM system property by launching the Solr it with:

In general, any Java system property that you want to set can be passed through the bin/solr script using the standard -Dproperty=value syntax. Alternatively, you can add common system properties to the SOLR_OPTS environment variable defined in the Solr include file (bin/solr.in.sh). For more information about how the Solr include file works, refer to: Taking Solr to Production.

Config API

The Config API allows you to use an API to modify Solr's configuration, specifically user defined properties. Changes made with this API are stored in a file named configoverlay.json. This file should only be edited with the API, but will look like this example:

For more details, see the section Config API.


If the configuration directory for a Solr core contains a file named solrcore.properties that file can contain any arbitrary user defined property names and values using the Java standard properties file format, and those properties can be used as variables in the XML configuration files for that Solr core.

For example, the following solrcore.properties file could be created in the conf/ directory of a collection using one of the example configurations, to override the lockType used.


solrcore.properties won't work in SolrCloud mode (it is not read from ZooKeeper). This feature is likely to be removed in the future. Instead, use another mechanism like a config overlay. 

The path and name of the solrcore.properties file can be overridden using the properties property in core.properties .

User defined properties from core.properties

Every Solr core has a core.properties file, automatically created when using the APIs.  When you create a SolrCloud collection, you can pass through custom parameters to go into each core.properties that will be created, by prefixing the parameter name with "property." as a URL parameter.  Example: 


That would create a core.properties file that has these properties and others omitted for brevity:

The my.custom.prop property can then be used as a variable, such as in solrconfig.xml:

Implicit Core Properties

Several attributes of a Solr core are available as "implicit" properties that can be used in variable substitution, independent of where or how they underlying value is initialized. For example: regardless of whether the name for a particular Solr core is explicitly configured in core.properties or inferred from the name of the instance directory, the implicit property solr.core.name is available for use as a variable in that core's configuration file...

All implicit properties use the solr.core. name prefix, and reflect the runtime value of the equivalent core.properties property:

  • solr.core.name
  • solr.core.config
  • solr.core.schema
  • solr.core.dataDir
  • solr.core.transient
  • solr.core.loadOnStartup

  • No labels


  1. I updated this page to try and better explain property substitution and the implicit properties.

    one thing i noticed while working on this however was this bug...


    ...so for now i kept the listof "implicit" properties short, since those are the only properties that whould always work because of how the defaults are defined. once SOLR-5262 is resolved, we should be able to remove the explicit list of implicit properties and just say something about how every "standard" core.property listed on the solr.xml page has an equivilent solr.core.foo implicit property

  2. iam trying to configure the velocity ui page but i face a problem with the query facets as it didn't retrieve any result after adding this line in solrconfig : <str name="facet.query">Egypt</str>

    and i tried a lot to change the keyword egypt to anything else but i got the same result , and i need help to fix it

    thanx in advance  (smile)

  3. Isn't the sentence "The solrconfig.xml file is located in the conf/ directory for each collection." out-dated for Solr 5.2? I don't see conf/schema.xml or even the conf dir in example/cloud/node1/solr/gettingstarted_shard1_replica1, for example, after executing instructions in the Solr tutorial. Some explanation of how Solr 5.2 finds the config files for each core is needed, IMHO. 


    1. This actually has nothing to do with the Solr version.

      The problem here is that this page doesn't talk about SolrCloud at all.  In SolrCloud, there is frequently no configuration on the disk at all.  Even if there is a conf directory with a solrconfig.xml file in it, Solr will not use it.  The active configuration for a collection in SolrCloud is found in the zookeeper database.

  4. This page should say right at the start something like:

    Values in solrconfig.xml can be overriden using configuration API (link) and will be stored in the file configoverlay.json.

    This will save a lot of troubleshooting time for newbies when they meet the system with overlays.

    1. good note alex, i modified the into para to call this out.

  5. I am receiving the below time out error :

    Exception: SolrNet.Exceptions.SolrConnectionException

    Message: The operation has timed out

    Source: SolrNet

       at SolrNet.Impl.SolrConnection.PostStream(String relativeUrl, String contentType, Stream content, IEnumerable`1 parameters)

       at SolrNet.Impl.SolrConnection.Post(String relativeUrl, String s)

       at SolrNet.Commands.OptimizeCommand.Execute(ISolrConnection connection)

       at SolrNet.Impl.SolrBasicServer`1.SendAndParseHeader(ISolrCommand cmd)

       at SolrNet.Impl.SolrBasicServer`1.Optimize(CommitOptions options)

       at Sitecore.ContentSearch.SolrProvider.SolrSearchIndex.PerformRebuild(Boolean resetIndex, Boolean optimizeOnComplete, IndexingOptions indexingOptions, CancellationToken cancellationToken)

       at Sitecore.ContentSearch.SolrProvider.SolrSearchIndex.Rebuild(Boolean resetIndex, Boolean optimizeOnComplete)

    1. Please ask questions like this on the appropriate user's list, comments here are intended for improving the  documentation, not usage questions. In this case I suggest you confer with the SolrNet user's list.

      This message will be deleted shortly.