> For the complete documentation index, see [llms.txt](https://docs.ama.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ama.one/sdk/9.-troubleshooting.md).

# 9. Troubleshooting

Common issues and solutions when using the Amadeus Protocol SDK.

### Installation Issues

#### "Module not found" Error

**Problem**: Cannot find module '@amadeus-protocol/sdk'

**Solutions**:

1. Ensure the package is installed:

   ```bash
   npm install @amadeus-protocol/sdk
   ```
2. Check your `package.json`:

   ```json
   {
   	"dependencies": {
   		"@amadeus-protocol/sdk": "^1.0.0"
   	}
   }
   ```
3. Clear cache and reinstall:

   ```bash
   npm cache clean --force
   rm -rf node_modules package-lock.json
   npm install
   ```

#### TypeScript Errors

**Problem**: Type errors when importing

**Solutions**:

1. Ensure TypeScript is installed:

   ```bash
   npm install -D typescript @types/node
   ```
2. Check `tsconfig.json`:

   ```json
   {
   	"compilerOptions": {
   		"moduleResolution": "node",
   		"esModuleInterop": true
   	}
   }
   ```
3. Restart your TypeScript server/IDE

#### Node.js Version Issues

**Problem**: Errors related to Node.js version

**Solutions**:

1. Check Node.js version:

   ```bash
   node --version
   ```
2. Update to Node.js 20+ if needed
3. Use a version manager like `nvm`:

   ```bash
   nvm install 20
   nvm use 20
   ```

### Runtime Errors

#### "Invalid Base58 string"

**Problem**: Error when decoding Base58 addresses or keys

**Causes**:

* Invalid Base58 encoding
* Missing or extra characters
* Wrong string format

**Solutions**:

```typescript
import { fromBase58 } from '@amadeus-protocol/sdk'

function validateBase58(str: string): boolean {
	try {
		fromBase58(str)
		return true
	} catch {
		return false
	}
}

// Validate before use
if (!validateBase58(address)) {
	throw new Error('Invalid Base58 address')
}
```

#### "Transaction failed: insufficient balance"

**Problem**: Transaction rejected due to insufficient funds

**Solutions**:

1. Check balance before transferring:

   ```typescript
   const balance = await sdk.wallet.getBalance(address, 'AMA')
   if (balance.balance.float < amount + fee) {
   	throw new Error('Insufficient balance')
   }
   ```
2. Account for transaction fees:

   ```typescript
   const requiredAmount = amount + AMA_TRANSFER_FEE
   ```

#### "Request timeout"

**Problem**: API requests timing out

**Causes**:

* Network connectivity issues
* Node is slow or overloaded
* Timeout too short

**Solutions**:

1. Increase timeout:

   ```typescript
   const sdk = new AmadeusSDK({
   	baseUrl: 'https://nodes.amadeus.bot/api',
   	timeout: 60000 // 60 seconds
   })
   ```
2. Implement retry logic:

   ```typescript
   async function submitWithRetry(txPacked: Uint8Array, maxRetries = 3) {
   	for (let i = 0; i < maxRetries; i++) {
   		try {
   			return await sdk.transaction.submit(txPacked)
   		} catch (error) {
   			if (i === maxRetries - 1) throw error
   			await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)))
   		}
   	}
   }
   ```

#### "Invalid transaction structure"

**Problem**: Transaction validation fails

**Causes**:

* Transaction not properly built
* Invalid arguments
* Wrong contract/function names

**Solutions**:

1. Always use `TransactionBuilder`:

   ```typescript
   const builder = new TransactionBuilder(privateKey)
   const { txPacked } = builder.transfer({
   	recipient: address,
   	amount: amount,
   	symbol: 'AMA'
   })
   ```
2. Validate inputs:

   ```typescript
   function validateTransferInput(input: TransferInput): boolean {
   	return (
   		isValidAddress(input.recipient) && input.amount > 0 && typeof input.symbol === 'string'
   	)
   }
   ```

#### "Invalid signature"

**Problem**: Transaction signature validation fails

**Causes**:

* Wrong private key used
* Transaction modified after signing
* Corrupted transaction data

**Solutions**:

1. Verify private key matches address:

   ```typescript
   const publicKey = derivePublicKeyFromSeedBase58(privateKey)
   if (publicKey !== expectedAddress) {
   	throw new Error('Private key does not match address')
   }
   ```
2. Don't modify transactions after signing:

   ```typescript
   // ✅ Good: Use txPacked directly
   await sdk.transaction.submit(txPacked)

   // ❌ Bad: Don't modify after signing
   // const modified = modifyTransaction(txPacked)
   ```

### API Errors

#### 404 Not Found

**Problem**: Resource not found

**Solutions**:

```typescript
try {
	const balance = await sdk.wallet.getBalance(address, 'AMA')
} catch (error) {
	if (error instanceof AmadeusSDKError && error.status === 404) {
		console.log('Address not found or has no balance')
		// Handle gracefully
	}
}
```

#### 400 Bad Request

**Problem**: Invalid request parameters

**Solutions**:

1. Validate inputs before API calls:

   ```typescript
   function isValidAddress(address: string): boolean {
   	try {
   		const bytes = fromBase58(address)
   		return bytes.length === 48
   	} catch {
   		return false
   	}
   }
   ```
2. Check error response for details:

   ```typescript
   catch (error) {
     if (error instanceof AmadeusSDKError) {
       console.error('Error details:', error.response)
     }
   }
   ```

#### Network Errors

**Problem**: Network connectivity issues

**Solutions**:

1. Check network connectivity:

   ```typescript
   async function checkConnection(): Promise<boolean> {
   	try {
   		await sdk.chain.getTip()
   		return true
   	} catch {
   		return false
   	}
   }
   ```
2. Use different node URL:

   ```typescript
   const sdk = new AmadeusSDK({
   	baseUrl: 'https://backup-node.com/api'
   })
   ```

### Transaction Issues

#### Transaction Stuck/Pending

**Problem**: Transaction submitted but not confirming

**Solutions**:

1. Check transaction status:

   ```typescript
   const tx = await sdk.transaction.get(txHash)
   console.log('Transaction status:', tx.receipt)
   ```
2. Wait for confirmation:

   ```typescript
   try {
   	const result = await sdk.transaction.submitAndWait(txPacked)
   	console.log('Confirmed:', result.metadata?.entry_hash)
   } catch (error) {
   	console.error('Confirmation timeout')
   }
   ```

#### Nonce Collisions

**Problem**: Multiple transactions with same nonce

**Causes**:

* Transactions submitted too quickly
* Timestamp-based nonce collision

**Solutions**:

1. Add delays between transactions:

   ```typescript
   async function submitMultiple(txs: Uint8Array[]) {
   	for (const tx of txs) {
   		await sdk.transaction.submit(tx)
   		await new Promise((resolve) => setTimeout(resolve, 100))
   	}
   }
   ```

#### Wrong Amount

**Problem**: Amount not matching expected value

**Causes**:

* Precision loss from manual calculation
* Wrong conversion

**Solutions**:

1. Always use conversion functions:

   ```typescript
   // ✅ Good
   const atomic = toAtomicAma(1.5)

   // ❌ Bad
   const atomic = 1.5 * 1000000000
   ```
2. Verify amounts:

   ```typescript
   const amount = 10.5
   const atomic = toAtomicAma(amount)
   const back = fromAtomicAma(atomic)
   console.log('Matches:', amount === back) // Should be true
   ```

### Encryption Issues

#### "Decryption failed"

**Problem**: Cannot decrypt encrypted data

**Causes**:

* Wrong password
* Corrupted encrypted data
* Missing IV or salt

**Solutions**:

1. Verify password:

   ```typescript
   try {
   	const decrypted = await decryptWithPassword(encrypted, password)
   } catch (error) {
   	if (error.message.includes('decryption')) {
   		console.error('Wrong password or corrupted data')
   	}
   }
   ```
2. Ensure all components are present:

   ```typescript
   const encrypted = {
   	encryptedData: stored.encryptedData,
   	iv: stored.iv,
   	salt: stored.salt
   }
   ```

### Debugging

#### Enable Verbose Logging

```typescript
// Log all API requests
const originalGet = sdk.client.get.bind(sdk.client)
sdk.client.get = async (...args) => {
  console.log('GET:', args)
  return originalGet(...args)
}

// Log transaction building
const builder = new TransactionBuilder(privateKey)
const unsignedTx = builder.buildTransfer({...})
console.log('Unsigned transaction:', {
  nonce: unsignedTx.tx.nonce.toString(),
  action: unsignedTx.tx.action,
  hash: toBase58(unsignedTx.hash)
})
```

#### Transaction Inspection

```typescript
// Inspect transaction before signing
const unsignedTx = builder.buildTransfer({
	recipient: address,
	amount: amount,
	symbol: 'AMA'
})

console.log('Transaction details:', {
	signer: toBase58(unsignedTx.tx.signer),
	nonce: unsignedTx.tx.nonce.toString(),
	contract: unsignedTx.tx.action.contract,
	function: unsignedTx.tx.action.function,
	args: unsignedTx.tx.action.args,
	hash: toBase58(unsignedTx.hash)
})
```

### Getting Help

#### Check Documentation

1. Review API Reference
2. Check Examples
3. Read Best Practices

#### Common Resources

* **GitHub Issues**: Report bugs and request features
* **Documentation**: Complete API reference
* **Examples**: Real-world usage examples

#### Reporting Issues

When reporting issues, include:

1. SDK version
2. Node.js version
3. Error message and stack trace
4. Code snippet that reproduces the issue
5. Expected vs actual behavior

### Next Steps

* [**Best Practices**: Security and development guidelines](/sdk/8.-best-practices.md)
* [**Examples**: Real-world usage examples](/sdk/7.-examples.md)
* [**API Modules**: Complete API reference](/sdk/5.-api-modules.md)