WSS Agent troubleshooting error code descriptions

Products

Cloud Secure Web Gateway - Cloud SWG

Issue/Introduction

When troubleshooting WSS agent issues, one of the first things to look at is the Support diagnostic log (WSS agent tray icon object below)

Support diagnostic log includes common messages and error codes

WSS agent error codes reported can be Application or OS (Windows, MacOS) specific

- 12007 error code below is an example of a Windows specific error code - https://docs.microsoft.com/en-us/windows/win32/wininet/wininet-errors

Error codes with context gives a potentially better starting point for troubleshooting

Environment

WSS agent (All versions)

Windows and MacOS platforms

Cause

No cause - providing more information for self diagnosing issues

Resolution

All WSS agent messages, logs, and statuses which refer to error codes are - in general - going to be found in one of these lists:

Application-Specific (cloud::ErrorCode):

Error codes 50 and lower could be application-specific errors, and correspond with the following values

1: eQueueFull (Command Queue is full)
2: eQueueEmpty (Command Queue is empty)
3: eQueueItemTooShort (The size specified in the command queue item was 0)
4: eQueueNotStarted (Command Queue has not been started)
5. eKernelDriverMissing (Kernel driver has not been loaded)
6: eKernelConnectionFailed (Unable to connect to kernel driver)
7: eKernelAddNotifierFailed (Unable to add notifier to kernel)
8: eServiceStopped (The service has been stopped)
9: eInvalidPath (Invalid path)
10: eInvalidFile (Invalid file)
11: eObjectNotInitialized (Object not initialized)
12: eAlreadyInitialized (Already initialized)
13: eNotInitialized (Not initialized)
14: eNotFound (Not found)
15: eCTCCommFailed (CTCComm failed)
16: eCTCResultDenied (CTC result was 'DENY')
17: eHostFileTampering (Host file tampering has been detected)
18: eConfigStoreTampering (CS tampering has been detected)
19: eInvalidParameter (Invalid parameter)
20: eObjectCreationFailed (Object could not be created)
21: eCloudConnectionFailed (Unable to connect to cloud)
22: eCloudConnectionDetectedProxy (A proxy was detected preventing connection to the cloud)
23: eCloudConnectionClosed (Cloud connection is closed or has not been opened)
24: eTunnelIsClosed (The tunnel has been closed)
25: eTunnelConnectionFailed (The tunnel has failed)
26: eTimedOut (A timeout has occurred)
27: eWrongMessageType (The message type was incorrect)
28: eInvalidState (The tunnel is in an invalid state)
29: eInvalidDigest (The hash digest was invalid)
30: eValidationFailed (The hash was invalid)
31: eClientAuthDenied (ClientAuthResponse status was 'DENY')
32: eClientAuthRetry (ClientAuthResponse status was 'RETRY')
33: eClientAuthError (ClientAuthResponse status was 'ERROR')
34: eAlreadyStarted (Cloud connection monitor has already been started)
35: eAlreadyStopped (Cloud connection monitor has already ben stopped)
36: eSSLInitializationFailed (SSL Library failed to initialize)
37: eSSLCertificateInvalid (The certificate returned by the server is not valid)
38: eDetectedPassiveMode (Service indicated that the agent should be passive)
39: eInvalidResponse (Agent received an unexpected response)
40: eHTTPProxyConnectDenied (Connection to HTTP Proxy was denied)
41: eInvalidURL (The given URL was invalid)
42: eInvalidProtocol (The requested protocol is not supported)
43: eHTTPHeaderError (The HTTP headers were invalid)
44: eHTTPConnectFailed (HTTP status code was not 200)
45: eInvalidDownloadSize (The requested file for download was invalid)
46: eHTTPReadFailed (Failed to read data from HTTP stream)
47: eHTTPDownloadHalted (HTTP download was explicitly halted)
48: eInvalidCipher (A Cipher has not been created)
49: eDecryptionFailed (Decryption of the data packet failed)
50: eEncryptionFailed (Encryption of the data packet failed)

Windows error codes:

Windows system error codes: https://docs.microsoft.com/en-us/windows/desktop/Debug/system-error-codes
Windows HTTP Service error codes: https://docs.microsoft.com/en-us/windows/win32/winhttp/error-messages

macOS error codes:

MacOS kernel error codes: https://opensource.apple.com/source/xnu/xnu-4903.221.2/bsd/sys/errno.h.auto.html
- On a machine with Xcode installed, these are located in:
  
  <PATH_TO_SDK_DIR*>/usr/include/sys/errno.h
https://developer.apple.com/documentation/foundation/1508628-url_loading_system_error_codes
- These error codes are more easily searched on a machine with Xcode installed. They are located in the file:
  
  <PATH_TO_SDK_DIR*>/System/Library/Frameworks/Foundation.framework/Headers/NSURLError.h
- The following list was taken from Xcode 12.5:
  
  NS_ERROR_ENUM(NSURLErrorDomain)
  {
  NSURLErrorUnknown = -1,
  NSURLErrorCancelled = -999,
  NSURLErrorBadURL = -1000,
  NSURLErrorTimedOut = -1001,
  NSURLErrorUnsupportedURL = -1002,
  NSURLErrorCannotFindHost = -1003,
  NSURLErrorCannotConnectToHost = -1004,
  NSURLErrorNetworkConnectionLost = -1005,
  NSURLErrorDNSLookupFailed = -1006,
  NSURLErrorHTTPTooManyRedirects = -1007,
  NSURLErrorResourceUnavailable = -1008,
  NSURLErrorNotConnectedToInternet = -1009,
  NSURLErrorRedirectToNonExistentLocation = -1010,
  NSURLErrorBadServerResponse = -1011,
  NSURLErrorUserCancelledAuthentication = -1012,
  NSURLErrorUserAuthenticationRequired = -1013,
  NSURLErrorZeroByteResource = -1014,
  NSURLErrorCannotDecodeRawData = -1015,
  NSURLErrorCannotDecodeContentData = -1016,
  NSURLErrorCannotParseResponse = -1017,
  NSURLErrorAppTransportSecurityRequiresSecureConnection API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0)) = -1022,
  NSURLErrorFileDoesNotExist = -1100,
  NSURLErrorFileIsDirectory = -1101,
  NSURLErrorNoPermissionsToReadFile = -1102,
  NSURLErrorDataLengthExceedsMaximum API_AVAILABLE(macos(10.5), ios(2.0), watchos(2.0), tvos(9.0)) = -1103,
  NSURLErrorFileOutsideSafeArea API_AVAILABLE(macos(10.12.4), ios(10.3), watchos(3.2), tvos(10.2)) = -1104,
  
  // SSL errors
  
  NSURLErrorSecureConnectionFailed = -1200,
  NSURLErrorServerCertificateHasBadDate = -1201,
  NSURLErrorServerCertificateUntrusted = -1202,
  NSURLErrorServerCertificateHasUnknownRoot = -1203,
  NSURLErrorServerCertificateNotYetValid = -1204,
  NSURLErrorClientCertificateRejected = -1205,
  NSURLErrorClientCertificateRequired = -1206,
  NSURLErrorCannotLoadFromNetwork = -2000,
  
  // Download and file I/O errors
  
  NSURLErrorCannotCreateFile = -3000,
  NSURLErrorCannotOpenFile = -3001,
  NSURLErrorCannotCloseFile = -3002,
  NSURLErrorCannotWriteToFile = -3003,
  NSURLErrorCannotRemoveFile = -3004,
  NSURLErrorCannotMoveFile = -3005,
  NSURLErrorDownloadDecodingFailedMidStream = -3006,
  NSURLErrorDownloadDecodingFailedToComplete =-3007,
  
  NSURLErrorInternationalRoamingOff API_AVAILABLE(macos(10.7), ios(3.0), watchos(2.0), tvos(9.0)) = -1018,
  NSURLErrorCallIsActive API_AVAILABLE(macos(10.7), ios(3.0), watchos(2.0), tvos(9.0)) = -1019,
  NSURLErrorDataNotAllowed API_AVAILABLE(macos(10.7), ios(3.0), watchos(2.0), tvos(9.0)) = -1020,
  NSURLErrorRequestBodyStreamExhausted API_AVAILABLE(macos(10.7), ios(3.0), watchos(2.0), tvos(9.0)) = -1021,
  
  NSURLErrorBackgroundSessionRequiresSharedContainer API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = -995,
  NSURLErrorBackgroundSessionInUseByAnotherProcess API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0)) = -996,
  NSURLErrorBackgroundSessionWasDisconnected API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0))= -997,
  };

Additional Information

Extracting the error codes and googling for more information can often provide bigger clues as to source of problem e.g. in the example of the 12007 error in screenshot above, the CTC service could not be reached because of general connectivity errors. Searching for 12007 windows errors would give countless of examples and solutions to such problems in various environments.