Docker is one of the chief prerequisites for the installation and configuration of IBM Planning Analytics Workspace (PAW). Every so often, it is possible that customers may run into docker-related issues which might prevent functioning of PAW.
This technote aims to help you through some commonly faced docker issues.
For the purposes of this technote, all Powershell commands mentioned should be run from an elevated Powershell session.
Given below is a workflow diagram of the troubleshooting approach this technote adopts. The text that follows the diagram walks the reader through each of the steps that they may have to take and explains the blocks in detail.
Diagram 1: PAW Troubleshooting Workflow
Issue 1: Cannot Access PAW in a browser/ PAW Services not coming up
Relevant Symptoms:
1. "Planning Analytics Workspace is unavailable. Try again in a few minutes" in web-browser
2. "This site can't be reached" in web-browser
- Make sure docker is up and running. Type the following commands in a powershell window to ensure the same:
- start-service docker
- Also please check the Windows Services to make sure "Docker Engine" is in running state
- In a Powershell session, navigate to the PAW install directory, and type in ./scripts/paw.ps1
- If the issue persists or if the script returns some error, jump to Issue 3
Issue 2: Admintool exits/Cannot launch Admintool
Relevant Symptoms:
1. "Something went wrong at step 'Starting IBM Planning Analytics Administration Tool' Execution failed with exit code 1" when Start.ps1 script is executed
2. "Cannot start service admintool: failed to create endpoint admintool on network nat: HNS failed with error : Element not found.
Encountered errors while bringing up the project." when Start.ps1 is executed
- Open <PAW-install-Location>/log/admintool/up.log and take a look at the error message
- If the error message mentions HNS, skip to Issue 4 of this technote
- If the log file error message does not mention HNS, from a powershell session, run ./scripts/paw.ps1
- If the issue persists, jump to Issue 3 of this technote
Issue 3: Running ./scripts/paw.ps1 fails to restart services/returns HNS errors/Windows Filter Errors/ pa-gateway errors
Relevant Symptoms:
1. "Recreating 32bf8925a845_32bf8925a845_32bf8925a845_admintool
Error: for <service-Name> Cannot start <service-Name>: hcsshim: PrepareLayer failed in Win32: The handle is invalid. (0x6) layerId=<ID> flavour=1" when ./scripts/paw.ps1 is executed
2. "For pa-gateway Cannot start service pa-gateway: failed to create endpoint pa-gateway on network nat: HNS failed" when ./scripts/paw.ps1 is executed
3. "HNS failed with error: The file cannot be opened because it is in the process of being deleted." when ./scripts/paw.ps1 is executed
4. "Cannot start service <service-Name>: failed to create endpoint <service-name> on network nat: HNS failed with error: The object already exists." when ./scripts/paw.ps1 is executed
5. "Cannot Start service <service-name>: Container is marked for removal and cannot be started" ./scripts/paw.ps1 is executed.
6. "C:\Program Files\Docker\docker.exe: failed to register layer: re-exec error: exit status 1: output: ProcessUtilityVMImage C:\ProgramData\docker\windowsfilter\<id>\UtilityVM: The process cannot access the file because it is being used by another process" when ./scripts/paw.ps1 is executed
It is also recommended to get confirmation from your AV vendor that the AV does support Windows containers.
Should you have to add exclusions to your AV scanning protocols, the following locations are recommended:
- C:\ProgramData\docker (Or the docker-root location in the daemon.json file)
- C:\ProgramData\Microsoft\Windows\HNS
- <PAW-Install-Location>
- In case of pa-gateway not starting, make sure nothing is running on port 80. If port 80 is free and issue/error persists or other containers are not coming up, please try the next step as below.
- In case of HNS Issues(Relevant symptom #'s 2/3/4), jump to Issue 4 of this technote
Issue 4: HNS Issues
It is sometimes possible that the docker networks get corrupted, which is where the Host Network Service (HNS comes into play)
-Run the script with the following syntax:
.\WindowsContainerNetworking-LoggingAndCleanupAide.ps1 -Cleanup -ForceDeleteAllSwitches
- If the script runs successfully, please restart the computer and then run the paw.ps1 script from the scripts folder
- If it errors out, please run the following commands from Powershell
- If either of the above commands fail, the issue lies at the Docker level as the hello-world container is completely disjoint from any IBM PAW services
- In that case, it is recommended to contact MS support for Docker issues. You can read more about that here:
- In extreme cases, it may be required to re-image the server because of a docker network corruption at the registry level. Please contact IBM Support to discuss available options or any further troubleshooting.
[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSD29G","label":"IBM Planning Analytics"},"Component":"Planning Analytics Workspace","Platform":[{"code":"PF033","label":"Windows"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB10","label":"Data and AI"}}]
