Why Am I Seeing the NacelleReference Message?

This article is meant to be a high-level explanation of why the NacelleReference message is displayed, if you would like steps to resolve this issue consult this article. 

If you're reading this article, you may have noticed the following message in one of your Contentful entries index by Nacelle:

"type": "NacelleReference",
"message": "Cannot find Nacelle reference"

At a high-level, this error indicates that Nacelle does not have the referenced piece of content in the index. This content could be another entry, asset, media, etc.

As you can imagine, there are any number of reasons why Nacelle would be unable to find the reference, from it not being published, to the references simply not existing. However, instead of outlining each of these possible edge-cases one-by-one, it may be better to look at the ingestion process from Nacelle's perspective, to better understand how things are discovered and stored. 

The Contentful Model

Let's start by defining a new content type, we'll call it a Test Banner (`testBanner`). The Test Banner will have two fields:

1. Title: Short text
2. Background: Media

In this model the Background field will always be a reference to an uploaded piece of media, in this case a photo. Here's what an entry may look like:

Notice in the example above the Background field is pointing to an image that is still in draft mode.

The Ingestion Process 

Once prompted — either by webhooks, or a manual re-index — Nacelle will make a request to the Contentful API to retrieve the newly created entry. This is the response Nacelle will receive:

The response from Contentful has quite a bit of metadata, but for our purposes the "fields" object is what we're interested in. Notice that it has the two fields from before: Title, and Background. Also notice that even though our background image is in draft mode it's ID still appears. 

Locating References 

Nacelle has ingested this entry, and we know that it has a reference. So our goal now is to ingest the reference. This should be easy, Nacelle will simply make a request using the ID provided. However, when Nacelle makes the request we get the following response:

 "message": "The resource could not be found.",

This is because our photo is in draft mode, and Contentful does not return any information on entries or assets that have not been published. This message is the same if the reference is unpublished, deleted, or just if the ID was just made up. As a result it is impossible to know what's happening within Contentful by API response alone.

Without any additional information from the Contentful API, Nacelle can only convey that "the resource could not be found," and as a result the NacelleReference message is displayed. 

In Summary

When a NacelleReference error is generated, it is because Contentful has returned an identical error message when Nacelle attempts to index a referenced data point.

For tips on resolving this error, please refer to this article.