Problems and corrective actions

This page tells you the causes of common problems in LUC Analytics (LUCA) and the actions that correct them.

Each table has three columns. "Problem" gives the message that the app or Docker shows, or what you see. The text in "double quotes" is the exact message. A control or a label of the app is in bold. A part such as {{code}} is a value that the app writes in the message.

Docker and the container

For the full procedures, see 01-install-and-start.md.

Problem	Cause	Action
docker run fails with a message that it could not bind host port 127.0.0.1:8000. On Linux, the message is address already in use.	A different program uses port 8000 on your laptop. Docker made the container, but did not start it.	1. Type docker rm luc-analytics. 2. Type the docker run command again with a different host port, for example -p 127.0.0.1:8080:8000. 3. In the link from the log, change 8000 to 8080.
"The container name "/luc-analytics" is already in use"	A container from an earlier docker run command exists.	Start that container with docker start luc-analytics. Or remove it with docker rm -f luc-analytics and type the docker run command again. The volume and your data stay.
Docker Desktop stays at "Engine starting", or it shows a WSL timeout.	The Docker engine or its WSL 2 virtual machine does not start correctly.	1. Right-click the Docker icon in the notification area of the taskbar. 2. Select Quit Docker Desktop. 3. Start Docker Desktop again. 4. If the problem continues, quit Docker Desktop again. 5. Type wsl --shutdown in PowerShell. 6. Start Docker Desktop again.
docker version shows no Server part.	The Docker engine is not started.	Start Docker Desktop. Wait until it shows Engine running.
The container stops at once. The log, or the output of docker run, contains exec format error.	The build of the image (amd64 or arm64) does not agree with the processor of your laptop.	1. Type $env:PROCESSOR_ARCHITECTURE in PowerShell. On a Mac, type uname -m in Terminal. 2. Type docker image inspect luc-analytics --format "{{.Architecture}}". 3. Compare the two values. AMD64 agrees with amd64. ARM64 agrees with arm64. On a Mac, x86_64 agrees with amd64 and arm64 agrees with arm64. 4. If the values do not agree, get the image file for the correct build (luc-analytics-beta-...-amd64.tar.gz or luc-analytics-beta-...-arm64.tar.gz). 5. Type docker rm luc-analytics. 6. Do the steps in "Load the image" in 01-install-and-start.md with the correct file. 7. Start the container again with the docker run command.
Settings > Memory shows "Not detected on this host — enter the memory limit of this machine or VM."	The app cannot find the memory limit inside Docker Desktop. Also, Docker possibly has too little memory: by default, it can use approximately half of the memory of the laptop.	1. Give Docker 5 GB of memory or more in the file .wslconfig. 2. Type wsl --shutdown and start Docker Desktop again. 3. In Settings > Memory, type the memory of Docker in Host / VM memory limit (GB). 4. Close other large programs.
The app does not answer in the browser.	The container is stopped, or the app has a problem.	1. Type docker ps -a to see if the container runs. 2. Type docker logs luc-analytics to read the messages from the app. 3. If the container is stopped, type docker start luc-analytics.
The app does not answer after you start Windows again.	The container does not start automatically.	Start Docker Desktop. Then type docker start luc-analytics.

Access key

WARNING: Do not give the link with the access key to other persons. A person with the link can use the app and your AWS credential.

Problem	Cause	Action
The browser shows "Access key required".	The browser does not have the access key.	1. Type docker exec luc-analytics cat /data/state/access-key. 2. Open http://localhost:8000/?access_key=<key>. Use the key from step 1.
The browser shows "Access key unavailable". The page says that the server "can no longer read one (its key file may have been deleted)".	The key file in the volume is not there, or the server cannot read it.	Restart the container with docker restart luc-analytics. The app makes a new key and writes a new link in the log. Open the new link.

AWS credential (Check credentials)

You find these messages in Settings > Credentials, after you push Check credentials. This check is free. For the settings, see 06-settings.md.

Problem	Cause	Action
"AWS rejected this credential ({{code}}): the access key ID or the secret is wrong, or the key is not active. Next: re-enter both, then Check credentials again."	The AWS access key ID or the AWS secret access key is wrong, or the AWS key is not active.	Type the two values again. Push Check credentials.
"No AWS credential is entered or saved. Next: enter the access key ID and secret, then Check credentials."	There is no AWS credential.	Type the AWS access key ID and the AWS secret access key. Push Check credentials.
"A stored credential exists but could not be read with the active secret-store key. Next: re-enter the access key ID and secret and save."	The key of the encrypted store changed, or the store is damaged.	Type the AWS access key ID and the AWS secret access key again. Push Save.
"AWS STS could not be reached (network or endpoint). This says nothing about the credential. Next: retry."	There is no network connection, or AWS does not answer.	Make sure that the laptop has an internet connection. Push Check credentials again.
"AWS STS did not answer in time. This says nothing about the credential. Next: retry."	AWS did not answer in the permitted time.	Push Check credentials again.
"Enter both the access key ID and the secret access key, or neither."	You typed only one of the two values.	Type the two values, or clear the two fields.
"Check the credentials first. A key pair that failed the check is never saved."	You pushed Save before a successful check.	Push Check credentials. When the check is successful, push Save.

Dataset connection (Test connection)

You find these messages for a dataset source after you push Test connection.

WARNING: Test connection makes a request to the WRI bucket. AWS sends the charge for this request to your AWS account.

Problem	Cause	Action
"Your credential is fine. This dataset's Requester pays setting is off, so the app is refusing to make a charged request. Turn on Requester pays above."	Requester pays is off. Without it, the app does not make a request that costs money.	Turn on Requester pays. Push Test connection again.
"AWS rejected this credential for this dataset. The key may have been revoked, may be wrong, or may not have permission. Requester pays is already on, so this is the credential."	The AWS credential is not correct, or it has no permission.	Push Check credentials. If the check fails, correct the AWS credential.
"AWS rejected this credential ({{code}}) — the credential, not the location. Next: press Check credentials."	AWS refused the credential.	Push Check credentials.
"No AWS credential is resolved for this dataset. Add an access key ID and secret above, then save and test again."	There is no AWS credential.	Type and save the AWS credential. Push Test connection again.
"A stored credential exists but could not be read with the active secret-store key. Re-enter the access key ID and secret above and save."	The app cannot decrypt the saved credential.	Type the AWS credential again and save it.
"AccessDenied ({{code}}): the key is valid but is not allowed to read this bucket, or the bucket refused the requester-pays request. Next: Check credentials, then the CLI check below."	The AWS key is correct, but it does not have permission to read the bucket.	1. Push Check credentials. 2. Do the check in Check it yourself from your own shell. 3. Give the AWS key the permission to read the bucket.
"The dataset could not be reached (network or endpoint failure). This is unrelated to your credential or the Requester pays setting."	There is no network connection, or the endpoint does not answer.	Make sure that the laptop has an internet connection. Push Test connection again.
"The connection test timed out. The dataset did not respond within the allowed time — this is likely a slow or unreachable endpoint, not your credential or the Requester pays setting."	The endpoint did not answer in the permitted time.	Push Test connection again later.
"AWS answered {{code}} for {{uri}}: nothing is at that location. Next: press Use manifest path ($, one billed request)."	The S3 path of the dataset is wrong or old.	Push Use manifest path. This makes one request that costs money.
"No objects exist under {{uri}}: the bucket answered, but nothing is stored at that prefix. Next: press Use manifest path ($, one billed request)."	There are no files at that S3 path.	Push Use manifest path. This makes one request that costs money.
"The location is reachable and authorized, but it does not contain a readable Zarr store."	The S3 path does not contain the dataset.	Correct the S3 path of the dataset.
"The bucket answers from {{bucketRegion}}, not {{region}} — WRI's bucket is in us-east-1. Next: correct datasets.upstream.region (or regions) in config.yaml."	The AWS region in the configuration is wrong.	1. Change datasets.upstream.region in /data/config.yaml to us-east-1. 2. Restart the container.

Basemap provider credentials

You find these messages on the cards for Planet, Google Maps and Copernicus (CDSE) in Settings > Credentials, after you push Test connection. The message starts with "Connection failed:".

Problem	Cause	Action
"The provider rejected this credential. Check the value, or that it still has permission."	The credential is wrong, or it has no permission.	Type the correct value. Push Test connection again.
"The provider could not be reached (network or endpoint failure). This is unrelated to your credential."	There is no network connection, or the provider does not answer.	Make sure that the laptop has an internet connection. Push Test connection again.
"The provider did not respond within the allowed time. This is likely a slow or unreachable endpoint, not your credential."	The provider did not answer in the permitted time.	Push Test connection again later.
"The provider is misconfigured on the server, so the credential could not be tested."	The configuration of the server for this provider is not correct.	Speak to the person who installed the app.
"Test the connection first. A failed connection is never saved."	You pushed Save before a successful test.	Push Test connection. When the test is successful, push Save.

Upload a list

For more information about lists, see 02-lists.md.

Problem	Cause	Action
"Uploads are disabled"	ingest.upload_enabled is not true in the configuration. An install that you upgraded keeps its old configuration file.	1. Make sure that the access key protects the app. 2. Set ingest.upload_enabled: true in /data/config.yaml. 3. Restart the container.
"Unsupported file type"	The app cannot read this type of file. The app does not accept KMZ (.kmz) files.	Use a CSV, Excel (.xlsx), GeoJSON, KML (.kml) or zipped shapefile (.zip) file. To use a KMZ file, extract the KML file from it.
"File too large" or "Too many locations"	The file is larger than the limit.	Divide the file into smaller files. Upload each file as a list.
"Spreadsheet too wide"	A row of the spreadsheet has too many columns.	Remove the columns that you do not need. Upload again.
"No locations found"	The file has no rows.	Make sure that the file has rows.
"We couldn’t find the location columns"	The app cannot find the columns with the coordinates.	Use Change field mapping to select the columns.
"That column isn’t in your file"	The column matches use a column that is not in the file.	Correct the column matches.
"No valid locations"	The coordinates are not correct.	Correct the coordinates.
"Archive couldn’t be opened" or "KML/KMZ couldn’t be read"	The file is damaged.	Export the file from its program again. Upload it again.
"Locations need a size"	The file has points with no size.	Give a size (an area or a radius) for the points.
"Choose a unit"	The size has no unit.	Select Area or Radius.
"Which map projection?" or "Projection not recognized"	The coordinates are not WGS 84 latitude and longitude.	Select the projection of the file.
"Datasets unavailable"	The datasets are not available at this time.	Try again later.
"Upload interrupted", "Upload expired" or "Commit failed"	The upload did not finish.	Upload the file again.
"Can’t reach the server"	The browser cannot connect to the app.	Make sure that the container runs (docker ps -a).

Exports

For more information about exports, see 05-exports.md.

Problem	Cause	Action
You cannot push Export or ⬇ Download CSV. The tooltip shows "CSV export becomes available once the analysis of this list is complete."	The analysis of the list is not complete.	Wait until the analysis of the list is complete. A list with the label Incomplete after Halt & commit does not become complete. For such a list, export each finished location.
"CSV export becomes available once the analysis of this list is complete."	The server refused a list export, because the analysis of the list is not complete.	Wait until the analysis of the list is complete. For a list with the label Incomplete, export each finished location.
"Export unavailable — no locations have been analyzed for this list yet, so there is nothing to export."	No location of the list is finished.	Wait until the analysis is finished.
"Export unavailable — this location’s analysis has not finished. Export becomes available once every analysis for it is complete."	An analysis of this location is not finished.	Wait until each analysis of the location is finished.
"The CSV downloaded, but its Data-used sidecar file (the source dataset dates) could not be downloaded."	The second file did not download.	Push the button again.
"PDF export unavailable — no locations have been analyzed for this list yet."	No location of the list is finished.	Wait until the analysis is finished.
"PDF export unavailable — the map and analysis layers are not ready to capture yet. Please wait and try again."	The map is not fully drawn.	Wait until the map is fully drawn. Push Download PDF again.
"PDF export unavailable — still waiting for: {{items}}. Please wait and try again."	The map waits for the items in the message, for example basemap tiles.	Wait. Push Download PDF again. If tiles failed to load, see "Maps" below.
"PDF export failed — the map view could not be captured. Try again once the map has finished drawing."	The app did not make an image of the map.	Wait until the map is fully drawn. Push Download PDF again.
"PDF export failed — the report could not be assembled." or "PDF export failed — the export request did not complete. Please try again."	The app did not make the PDF file.	Push Download PDF again. If the problem continues, read the line that starts with "Cause:".
"The data sources could not be loaded. See DATA-ATTRIBUTION.md in the project repository."	The app did not get the attribution text.	Read the file DATA-ATTRIBUTION.md. Open Data sources and licenses again later.

Maps

For more information about maps, see 04-maps.md.

Problem	Cause	Action
"The map could not be shown"	An error occurred in the map. The other parts of the page continue to work.	Try again, or load the page again.
"Failed to load map grid data."	The app did not get the analysis layers for the map.	Load the page again.
"Locations found, but map bounds are invalid and cannot be displayed."	The boundaries of the locations are not correct.	Examine the coordinates of the locations.
"Compare is unavailable: this basemap has no dates to pick."	The basemap has no dates.	Select a different basemap.
"Native cells are smaller than a screen pixel at this zoom. Zoom in for Max resolution."	You zoomed out too far for Max resolution.	Zoom in.
"This file is not valid JSON." or "This is not a Map Key template file."	You selected a file that is not a map key template.	Select a .mpky file that you saved from the map key.

Lists and results

Problem	Cause	Action
"Failed to load lists" or "Failed to load results"	The app cannot read the results database.	Load the page again. If the problem continues, read the output of docker logs luc-analytics.
"List not found"	The list does not exist. Possibly, someone deleted it.	Go to the lists page and select a list that exists.
"This run did not finish: {{message}}"	A new run of the list stopped.	Read the message. Correct the cause. Then push Run again with current data.
"This update did not finish: {{message}}. The previous results are kept."	An update of the list stopped. The app keeps the earlier results.	Read the message. Start the update again.
"Something went wrong"	The page had an error.	Try again, or load the page again.