Troubleshooting

Common Issues

Error: agent 'demo-1' not found

• Verify the agent name with clish agent show
• Check if the agent was created successfully

• Generate a new token with clish agent onboarding-token issue
• Ensure agent uses the correct token for connection

Credential validation issues

Error: The agent does not respond to credential validation within timeout period

• Agent cannot reach the SVM (network issues, firewall blocking)
• Agent is overwhelmed or unresponsive
• SVM is down or unreachable

1. Re-onboard the agent and issue a new onboarding token via Management Service CLI:
   clish agent re-onboard --instance <agent-name>
2. Modify the config.yaml file in the Ontap agent installation folder (default: C:\Program Files\v1fs-ontap-agent\)
3. Remove the device_token key and its value
4. Add the onboarding_token key with the newly issued token:
   onboarding_token: eyJh......
5. Start the Ontap agent service (v1fs-ontap-agent)
6. Verify the agent connection status using Management Service CLI
7. After the agent connects successfully, re-enter credentials using:

   clish agent credential modify --instance
       <agent-name>

8. Review agent logs for SVM connection errors:
9. Test network connectivity from the agent to SVM:
   • Verify SVM management LIF is reachable from agent pod
   • Check firewall rules between agent and SVM

Note When validation fails or times out, credentials are automatically rolled back to the previous working version to prevent service disruption.

Credentials rejected by SVM

Error: Agent rejected credentials: Failed to connect to SVM: authentication failed

• Invalid username or password
• SVM user account is locked, expired, or disabled
• User lacks required permissions on SVM
• ONTAP API is not accessible

1. Verify credentials are correct:
   • Check username spelling and case sensitivity
   • Ensure password matches SVM user account
   • Verify you're using the correct SVM management credentials
2. Check SVM user account status (on ONTAP CLI):
   security login show -user-or-group-name <username> -vserver <svm-name>
   Look for:
   • Account locked status
   • Password expiration
   • Authentication method (should be "password" or "domain")
3. Verify user has appropriate permissions:
   • User should have at least readonly or vsadmin role for the SVM
   • Check role assignments:
     security login show -vserver <svm-name> security login role show -vserver <svm-name> -role <role-name>
4. Check SVM API access:
   # On ONTAP CLI vserver services web show -vserver <svm-name>
   Ensure ONTAPI and REST API are enabled
5. Review ONTAP audit logs for failed authentication attempts:

   # On ONTAP CLI 
   event log show -severity error -message-name *authentication*

Agent state invalid for credential update

Error: agent 'demo-1' is in state 'onboarding', cannot set credentials

• Agent must be in credential-required or running state to accept credential updates
• Agent may be stuck in a transitional state

1. Check the current agent state:
   clish agent show --instance <agent-name>
   Note the State and Connected fields
2. If the agent is stuck in onboarding state:
   • Verify the agent has completed initial onboarding process
   • Check if the agent successfully connected with onboarding token
3. If the agent is in init state:
   • The agent needs to complete initial connection first
   • Ensure the onboarding token is correctly configured in agent config
   • Restart the agent with valid onboarding token
4. If the agent is in disconnected state:
   • Verify network connectivity between agent pod and management service
   • Check the management service logs for connection errors

Agent not connected via WebSocket

Error: agent 'demo-1' is not connected via WebSocket, cannot validate credentials

• Credential validation requires an active WebSocket connection to send credentials and receive validation result
• The agent service may be down, restarting, or having network issues

1. Verify that the agent service is running.
2. Check the agent connection status:
   clish agent show --instance <agent-name>
   Look for Connected: disconnected
3. Review the agent logs for WebSocket connection errors
4. Check the network connectivity:
   • Verify that the agent can reach management service WebSocket endpoint
   • Check for network policies or firewalls blocking WebSocket connections
5. Wait for the agent to reconnect:
   • Agents automatically attempt to reconnect on disconnection
   • Monitor connection status
6. If the agent does not reconnect, check if the device token has expired (may need clish agent re-onboard)

Useful Commands for Debugging

clish agent show

clish agent show --instance <agent-name>

clish scanner scan-policy show